回调事件列表

分页查询当前账户、当前网络下的回调事件摘要，查看当前轮次的投递状态和最近错误。

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

请求地址

GET /open/v1/webhooks

鉴权请求头

先获取 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>

Query 参数

字段	类型	必填	说明	示例值
page	integer（Query 字符串）	否	页码，默认 1，最小为 1；空值按默认值处理。当前服务要求 page × page_size 不超过 9223372036854775807。	1
page_size	integer（Query 字符串）	否	每页数量，默认 20，范围 1–100；空值按默认值处理。	20

无路径参数，仅接受表中分页参数，不接受 event_type、status、时间、地址或其他 Query 字段；未知字段和重复 Query 键均返回 400。

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

记录按 created_at DESC, id DESC 排序。查询超过最后一页时仍为 HTTP 200，items 为空数组，total 保留总数。

GET /open/v1/webhooks?page=1&page_size=20

成功响应

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 完整字段

字段	类型	必填	说明	示例值
items	object[]	是	当前页记录；无记录或超过最后一页时为 []，不是 null。	见下方示例
total	integer	是	符合范围和筛选条件的记录总数，不是当前页数量。	1
page	integer	是	实际使用的页码。	1
page_size	integer	是	实际使用的每页数量。	20

data.items[] 完整字段

字段	类型	必填	说明	示例值
id	string	是	固定回调事件 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

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "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",
        "network": "nile"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

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

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

本页摘要不包含 payload、各轮次的 URL 或逐次响应正文。用事件 id 查询回调详情、投递轮次和投递尝试。

典型错误

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

分页不是整数、page < 1 或 page_size 不在 1–100 范围内时返回 HTTP 400。

HTTP 400：分页超出范围

{
  "code": 400,
  "message": "page or page_size out of range",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 400：发送未支持的筛选字段 status

{
  "code": 400,
  "message": "unknown field: status",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

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

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

完整字段与状态

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