回调事件详情

查询一个回调事件的当前投递摘要和完整业务 payload，定位对应到账、归集结果。

本页 ID、地址、URL、交易哈希、金额和时间均为文档示例，请替换成自己账户的数据。所有 ID 和金额使用字符串；计数、页码与 HTTP 状态码使用 JSON 数值。金额使用六位精度最小单位字符串，例如 "100000000" 表示 100 USDT，"1000000" SUN 表示 1 TRX。

请求地址

http

GET /open/v1/webhooks/{id}

鉴权请求头

先获取 access token，再按签名规则为实际请求生成 HMAC-SHA256 签名。四个鉴权头必须且只能提供一次。

字段	类型	必填	说明	示例值
X-App-Id	string	是	规范正整数 appID。	`1234567890`
X-Timestamp	string	是	当前 Unix 秒级时间戳，规范十进制字符串；有效时间窗口见签名指南。	`1788825600`
X-Sign	string	是	本次请求的 64 位小写十六进制 HMAC-SHA256 签名。	`<本次请求签名>`
Authorization	string	是	当前有效的 Bearer token。	`Bearer <ACCESS_TOKEN>`

路径参数

字段	类型	必填	说明	示例值
id	string	是	通知事件 ID，即业务正文的 event_id；不是到账记录 ID。	`123456789012345680`

事件必须属于当前账户和当前网络；不存在、其他账户或其他网络的事件统一返回 404。

不接受任何查询参数，包括 network 和 id；未知字段和重复 Query 键返回 400。路径 id 是事件 ID，不是轮次 ID 或单次尝试 ID。

GET 请求体必须为空；不需要 request_id，不要发送 Idempotency-Key 请求头。当前服务按账户和网络限定可读范围。读取不会触发投递或创建新轮次。

成功响应

HTTP 200，响应 Content-Type: application/json，Cache-Control: no-store。

字段	类型	必填	说明	示例值
code	integer	是	成功时固定为 0。	`0`
message	string	是	成功时固定为空字符串。	`""`
data	object	是	本次请求的响应对象。	见下方示例
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"

`data` 完整字段

字段	类型	必填	说明	示例值
id	string	是	通知事件 ID，即业务正文的 event_id；不是到账记录 ID。	`123456789012345680`
event_type	string	是	事件类型：deposit.confirmed、deposit.reverted，或 sweep 的 succeeded、failed、cancelled；完整枚举见下文。	`deposit.confirmed`
status	string	是	事件当前投递状态：pending / delivering / delivered / failed。	`delivered`
attempts	integer	是	当前轮次已开始的尝试次数，0–20；不是所有轮次累计次数。	`1`
current_round	integer	是	当前轮次编号，从 1 开始；重推会递增。	`1`
next_attempt	string 或 null	是	当前轮次下次尝试时间，RFC 3339 带时区；轮次结束为 null。	`null`
deadline_at	string	是	当前轮次截止时间，RFC 3339 带时区。	`2026-09-08T00:10:00Z`
last_error	string	是	当前保存的最近错误；没有错误时为空字符串。	`""`
created_at	string	是	原始事件创建时间，RFC 3339 带时区；重推不重置。	`2026-09-08T00:00:00Z`
delivered_at	string 或 null	是	成功送达时间，RFC 3339 带时区；未送达为 null。	`2026-09-08T00:00:02Z`
payload	object	是	保存的明文业务对象，结构由 event_type 决定；不是 null。	见下方两种完整示例

event_type 完整取值为 deposit.confirmed、deposit.reverted、sweep.succeeded、sweep.failed、sweep.cancelled。其中 deposit 是到账确认或撤销，sweep 是 USDT 归集结果。

status 描述回调投递：pending 等待发送，delivering 正在投递，delivered 已获得有效成功应答，failed 当前轮次已结束且未成功送达。回调状态不改变到账或转账的链上业务结果。

`data.payload` 共同字段

到账正文为24个字段，与到账详情的data、到账列表的单条items完全一致；归集结果正文为11个字段。下面先列共同字段，再列各类完整说明。

字段	类型	必填	说明	示例值
event_id	string	是	本次状态事件 ID；重试不变，撤销/重新确认产生新事件 ID。按此字段去重。
event_type	string	是	事件类型，决定下述 payload 结构。	`deposit.confirmed`
network	string	是	事件所属 TRON 网络：main（主网）或 nile（测试网络）。	`nile`
wallet_id	string	是	业务钱包 ID：到账为收款钱包，归集为转出钱包。	`123456789012345678`
amount	string	是	业务记录最小单位金额；到账/归集为 USDT。到账为正整数，任务结果可为 "0"。	`"100000000"`
txid	string	是	到账为交易哈希；任务未生成交易时可为空字符串。	`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

deposit.confirmed / deposit.reverted 的完整 24 个字段

此对象与到账详情使用同一结构；同一 id、revision 的内容一致。data.status表示推送状态，data.payload.status为confirmed（达到租户确认门槛）或reverted（到账已撤销），两者不要混淆。

字段	类型	必返	说明
id	string	是	到账记录 ID，同一交易日志即使撤销后重新确认也保持不变。
event_id	string	是	本次状态事件 ID；重试不变，撤销/重新确认产生新事件 ID。按此字段去重。
event_type	string	是	到账状态事件类型。 deposit.confirmed 表示到账认可；deposit.reverted 表示到账撤销。
status	string	是	到账状态：confirmed 表示达到租户确认门槛；reverted 表示因链重组撤销。不是推送状态。
wallet_id	string	是	收款钱包 ID。
custom_id	string	是	钱包的租户自定义ID，同一租户内唯一，取到账入库时快照。
chain	string	是	所属区块链。固定值："TRON"。
network	string	是	资产所属网络：main（主网）或 nile（测试网络）。
asset	string	是	资产名称；测试网对应测试代币。资产身份以network+contract为准。固定值："USDT"。
token_standard	string	是	代币协议。固定值："TRC20"。
decimals	integer	是	金额精度，展示金额=amount÷10^decimals。使用整数或十进制定点计算。固定值：6。
address	string	是	到账收款地址。
source	string	是	链上 Transfer 事件的来源地址。
contract	string	是	此笔Transfer的实际代币合约。结合network识别资产；Nile为测试代币，Main为Tether发行的USDT。
amount	string	是	该条到账记录的 USDT 金额，是否有效由 status 决定；最小单位的整数字符串，六位精度，禁止用浮点数处理。
txid	string	是	该条到账对应的交易哈希。
log_index	integer	是	交易收据内的日志索引；与网络、交易哈希一起标识链上事件。
block_number	string	是	到账状态对应的区块高度，低确认模式下不代表已固化。
block_time	string	是	链上区块时间；UTC RFC3339，固定6位小数秒，以Z结尾。不是通知发送时间。
created_at	string	是	平台确认并保存到账的时间；UTC RFC3339，固定6位小数秒，以Z结尾。确认或同步存在延迟时，可能晚于 block_time。
revision	integer	是	同一到账状态版本，从1递增；只应用更高版本，旧版本通知应答成功但不再入账。
confirmation_type	string	是	该笔到账采用的确认规则：block_1、block_3、block_6、block_12、solidified。仅平台开通的确认规则。
confirmations	integer / null	是	通过最新区块确认时的确认数；按固化结果确认时为 null。
block_hash	string / null	是	本次状态对应的区块哈希；既有历史记录未保存时为null。

json

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "id": "123456789012345680",
    "event_type": "deposit.confirmed",
    "status": "delivered",
    "attempts": 1,
    "current_round": 1,
    "next_attempt": null,
    "deadline_at": "2026-09-08T00:10:00Z",
    "last_error": "",
    "created_at": "2026-09-08T00:00:00Z",
    "delivered_at": "2026-09-08T00:00:02Z",
    "payload": {
      "id": "123456789012345680",
      "event_id": "123456789012345680",
      "event_type": "deposit.confirmed",
      "status": "confirmed",
      "wallet_id": "123456789012345678",
      "custom_id": "customer-1001",
      "chain": "TRON",
      "network": "nile",
      "asset": "USDT",
      "token_standard": "TRC20",
      "decimals": 6,
      "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
      "source": "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb",
      "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
      "amount": "100000000",
      "txid": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "log_index": 0,
      "block_number": "34567890",
      "block_time": "2030-01-01T00:00:00.000000Z",
      "created_at": "2030-01-01T00:00:01.000000Z",
      "revision": 1,
      "confirmation_type": "solidified",
      "confirmations": null,
      "block_hash": null
    }
  }
}

`sweep.*` 的 5 个专属字段

字段	类型	必填	说明	示例值
task_id	string	是	归集任务 ID；当前结果事件的 event_id 与 task_id 相同。	`123456789012345680`
destination	string	是	该任务的接收地址：归集目标地址。	`TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8`
status	string	是	业务终态：succeeded / failed / cancelled；与 event_type 后缀一致。	`succeeded`
reason	string	是	任务失败或取消原因；没有记录时为空字符串。	`""`
actual_fee	string	是	该任务已结算的实际链上手续费，单位 SUN；未产生已确认费用为 "0"。	`"1000000"`

任务结果事件可以是 sweep.succeeded、sweep.failed、sweep.cancelled。以下以归集成功为例，三种类型使用相同字段结构。

json

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "id": "123456789012345680",
    "event_type": "sweep.succeeded",
    "status": "delivered",
    "attempts": 1,
    "current_round": 1,
    "next_attempt": null,
    "deadline_at": "2026-09-08T00:10:00Z",
    "last_error": "",
    "created_at": "2026-09-08T00:00:00Z",
    "delivered_at": "2026-09-08T00:00:02Z",
    "payload": {
      "event_id": "123456789012345680",
      "event_type": "sweep.succeeded",
      "network": "nile",
      "task_id": "123456789012345680",
      "wallet_id": "123456789012345678",
      "amount": "100000000",
      "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
      "txid": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
      "status": "succeeded",
      "reason": "",
      "actual_fee": "1000000"
    }
  }
}

任务在金额确定前失败时，amount 可为 "0"；签名前失败或取消时 txid 可为空字符串。reason 和 actual_fee 始终存在，分别可为 "" 和 "0"。失败事件中的 amount 不代表已经到账，业务结果以 payload.status 为准。

详情的 payload 返回保存的明文业务对象，不包含 AES 加密外层的 version、algorithm、nonce 或 ciphertext。真实投递使用加密外层，请按回调通知指南接收。归集 payload 不含 sweep_mode、requested_amount、address 或创建/更新时间；需要归集任务字段时使用归集详情。

事件 id 和业务 payload 在自动重试及新建重推轮次时保持不变；轮次和逐次响应见投递轮次、投递尝试。

典型错误

错误响应不含 data；鉴权、账户状态、限流和超时等通用错误见通用错误说明。

事件 ID 格式非法时返回 HTTP 400；事件不存在或不属于当前账户和网络时返回 HTTP 404。

HTTP 400：事件 ID 不是规范正整数

json

{
  "code": 400,
  "message": "id must be a positive integer string",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 404：当前账户和网络下找不到事件

json

{
  "code": 404,
  "message": "record not found",
  "error_code": "RESOURCE_NOT_FOUND",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 401：token 缺失、无效或已过期

json

{
  "code": 401,
  "message": "authentication required or expired",
  "error_code": "TOKEN_INVALID_OR_EXPIRED",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

完整字段与状态

查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。

回调事件详情 ​

请求地址 ​

鉴权请求头 ​

路径参数 ​

成功响应 ​

data 完整字段 ​

data.payload 共同字段 ​

deposit.confirmed / deposit.reverted 的完整 24 个字段 ​

sweep.* 的 5 个专属字段 ​

典型错误 ​

HTTP 400：事件 ID 不是规范正整数 ​

HTTP 404：当前账户和网络下找不到事件 ​

HTTP 401：token 缺失、无效或已过期 ​

完整字段与状态 ​

回调事件详情

请求地址

鉴权请求头

路径参数

成功响应

`data` 完整字段

`data.payload` 共同字段

deposit.confirmed / deposit.reverted 的完整 24 个字段

`sweep.*` 的 5 个专属字段

典型错误

HTTP 400：事件 ID 不是规范正整数

HTTP 404：当前账户和网络下找不到事件

HTTP 401：token 缺失、无效或已过期

完整字段与状态