A webhook callback is a mechanism where, when specific events occur, WaaS proactively sends notifications to the merchant system to asynchronously inform about the results or status changes of certain operations.
Merchants need to provide a callback URL and implement the necessary functionality to receive and process these callbacks.
Example Scenarios
Below are examples of common callback workflows:
1. Deposit Notification Workflow
- The merchant submits a deposit request to the WaaS deposit AP
- WaaS processes the deposit request.
- WaaS calls the callback URL provided by the merchant to notify the deposit result.
- The merchant receives the notification and updates the status
2. Withdrawal Notification Workflow (No Secondary Confirmation)
- The merchant submits a withdrawal request to the WaaS withdrawal API.
- WaaS processes the withdrawal request.
- WaaS calls the merchant’s callback URL to notify the withdrawal result (success or failure).
- The merchant receives the notification and updates the status.
For withdrawal workflows that require secondary confirmation, the callback may include additional confirmation steps. Please ensure that your callback URL can correctly handle all notification scenarios.
The callback interface has the following functions:- Notify merchants about the creation of deposit orders.
- Request merchant confirmation of withdrawal details before execution.
- Notify merchants about user wallet address changes.
- Notify merchants of the execution results of withdrawal orders.
Note
The callback interface is used to receive notifications sent by WaaS. Merchants must provide WaaS with a callback address to receive event results through the callback mechanism. All requests must use the same API-Key mechanism for authentication as other interfaces. The notification content is RSA encrypted， before being sent, and the ciphertext is in Base64 format。
API Example
- API Endpoint：
https://xxxx/api/v1/uu/notify
Request Method
POST
| Name | Type | Required | Example Value | Description |
|---|
Content-Type | string | Yes | application/x-www-form-urlencoded | Request Format: Form-Encoded Format |
X-API-KEY | string | Yes | your-api-key | Authorization key for authentication. |
Request Body Parameters
Below is the request body parameter template:
| Attribute Name | Type | Required | Example Value | Description |
|---|
tenantUserId | String | Yes | tenant123 | Merchant user identifier. |
requestUUID | String | Yes | 2137890 | Unique identifier for the request. |
trackingId | String | Yes | track-4567 | Order tracking ID. |
type | Integer | Yes | 2 | Callback type |
business | Integer | Yes | 0 | Tenant type (no actual control effect currently). |
callBackId | String | No | 12345 | Callback ID. |
toAddress | String | No | TUekuiBgdk... | Target address. |
chainName | String | No | TRON | Blockchain name. |
txId | String | No | 22e1c72076... | Transaction ID. |
symbol | String | No | USDT | Symbol |
amount | String | No | 0.5 | Amount |
txIndex | Integer | No | 20 | Transaction index. |
tag | String | No | WITHDRAW_SUCCESSS | Tag |
fromAddress | String | No | TUekuiBgdk... | Source address. |
newAddress | String | No | TUekuiBgdk... | New address (only used when type is 4). |
riskLevelFrom | Integer | No | 15 | Risk score of the source address (exists when type is 1). |
riskLevelTo | Integer | No | 15 | Risk score of the target address (exists when type is 1). |
Callback Type Enum
Below are the enum values for the type parameter and their descriptions:
| Type | Enum Name | Description |
|---|
0 | NOTIFY_UNKNOWN | Unknown notification type, no action required. |
1 | NOTIFY_DEPOSITED | WaaS notifies the merchant of deposit order creation; parameters should be parsed and result confirmed. |
2 | NOTIFY_REQUEST_WITHDRAW | Requests merchant to confirm withdrawal order details (for secondary confirmation). |
3 | NOTIFY_WITHDRAW | WaaS notifies the merchant of withdrawal order execution result. |
4 | NOTIFY_ADDRESS | Notifies user address change; the new address (newAddress) should be parsed. |
5 | NOTIFY_INVALID_ADDRESS | Withdrawal failed (invalid address); confirmation and response required. |
6 | NOTIFY_NOT_ENOUGH_MONEY | Withdrawal failed (insufficient balance); confirmation and response required. |
7 | NOTIFY_NOT_ENOUGH_HOT_MONEY | Withdrawal failed (insufficient gas); confirmation and response required. |
Request Example
{
"tenantUserId": "tenant123",
"requestUUID": "2137890",
"trackingId": "track-4567",
"type": 2,
"business": 0,
"callBackId": "12345",
"toAddress": "TUekuiBgdk...",
"chainName": "TRON",
"txId": "22e1c72076...",
"symbol": "USDT",
"amount": 0.5,
"txIndex": 20,
"tag": "WITHDRAW_SUCCESSS",
"fromAddress": "TUekuiBgdk...",
"newAddress": "TUekuiBgdk...",
"riskLevelFrom": 15,
"riskLevelTo": 15
}
Response Parameters
| Attribute Name | Type | Required | Example Value | Description |
|---|
requestUUID | String | Yes | 2137890 | Unique identifier for the request. |
userId | String | Yes | 1308764 | Tenant ID. |
createBy | String | Yes | “ | Information about the creator (no actual control effect). |
message | String | Yes | “ | Description message (no actual control effect). |
apiKey | String | Yes | “ | apiKey |
errCode | int | Yes | “ | Error code: 0 indicates success; other values indicate failure. |
data | String | Yes | “ | Encrypted data using an RSA public key. |
| Attribute Name | Type | Example Value | Description |
|---|
requestUUID | String | 2137890 | Unique identifier for the request, used to uniquely identify it. |
userId | Integer | 1 | User ID, identifies the specific user who triggered the event. |
trackingId | String | track-4567 | Order tracking ID. |
address | String | toAddress123 | Target address, indicates the operation’s target address. |
tenantUserId | String | tenant123 | Merchant user identifier, used to differentiate merchant users. |
chainName | String | TRON | Blockchain name, identifies the blockchain where the transaction occurred. |
symbol | String | USDT | Currency symbol, identifies the token or currency involved in the transaction. |
callBackId | String | 12345 | Callback ID, identifies the current callback event. |
amount | String | 0.5 | Amount, indicates the specific transaction or operation amount. |
type | Integer | 2 | Callback type, detailed explanation can be found in the callback type |
Response Example
{
"requestUUID": "2137890" ,
"userId": 1,
"createBy":"xxxx",
"message": "成功处理请求",
"apiKey": "your_api_key",
"errCode": 0,
"data": {
"userId": 1,
"trackingId": "track-4567",
"address": "toAddress123",
"tenantUserId": "tenant123",
"chainName": "TRON",
"symbol":"USDT",
"callBackId":"12345",
"requestUUID": "2137890",
"amount": 0.5,
"type": 2,
}
}
