Webhook 回调

概述

当充值达到链确认数后，系统会向你配置的回调地址发送通知。

• Method: POST
• Content-Type: application/json
• 回调方向: 平台 -> 商户服务

触发时机

• 事件类型: deposit.confirmed
• 触发条件: 充值达到 requiredConfirmations
• 说明: 回调发生在充值确认后，不等待归集完成

事件粒度（重要）

• 一个链上 Transfer log 对应一个 webhook 回调（1 log = 1 webhook）。
• 同一笔交易（同一 txId）如果包含多个命中转账事件，会收到多条 webhook。
• 同一区块内如果有多笔命中交易，也会收到多条 webhook。
• 当前回调体中的 transfer 仅表示单个转账事件，不是批量数组。
• 请勿依赖回调到达顺序，建议以 transfer.transferId 做幂等入账。

请求 Header

Header	必填	说明
x-token	是	回调鉴权 token（由平台与商户预先约定）
Content-Type	是	application/json

请求体

顶层字段

字段	类型	必填	说明
type	string	是	固定为 deposit.confirmed
chainCode	string	是	链编码，如 ETH / BSC / TRON
txId	string	是	交易哈希；TRON 使用不带 0x 的 txId
blockNumber	integer	是	区块高度
confirmations	integer	是	当前确认数
requiredConfirmations	integer	是	目标确认数
transfer	object	是	本次确认的转账明细

transfer 字段

字段	类型	必填	说明
transferId	string	是	全局唯一转账 ID，格式：{CHAIN}:{txId}:{logIndex}
logIndex	integer	是	同一交易中的事件序号（原生转账一般为 0）
thirdPartyUserId	string	是	商户侧用户 ID（用于识别入账用户）
tokenCode	string	是	币种编码，如 USDT
contractAddress	string	否	代币合约地址；原生币可为空
from	string	是	链上转出地址
to	string	是	链上转入地址（平台充值地址）
amount	string	是	人类可读金额（十进制字符串）
rawAmount	string	是	原始金额（最小单位）
decimals	integer	是	小数精度

回调示例

{
  "type": "deposit.confirmed",
  "chainCode": "TRON",
  "txId": "4b829d34352faf1306e00e97537300df2a2ba26c386f6dbae80184f353c51c49",
  "blockNumber": 80624807,
  "confirmations": 20,
  "requiredConfirmations": 20,
  "transfer": {
    "transferId": "TRON:4b829d34352faf1306e00e97537300df2a2ba26c386f6dbae80184f353c51c49:11",
    "logIndex": 11,
    "thirdPartyUserId": "third-user-1",
    "tokenCode": "USDT",
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "from": "TFromAddress",
    "to": "TToAddress",
    "amount": "1",
    "rawAmount": "1000000",
    "decimals": 6
  }
}

回调响应约定

• 你方返回 2xx：视为投递成功
• 你方返回非 2xx / 超时 / 网络错误：平台会自动重试

重试策略

• 单次执行内快速重试（默认最多 3 次）
• 持久化队列重试（秒）：1, 3, 10, 30, 120, 300, 600, 1800, 7200, 21600, 43200
• 最大总重试次数默认 15，超过后标记失败

幂等建议

请基于 transfer.transferId 做幂等处理，确保重复回调不会重复入账。