回调投递尝试

分页查询回调事件的单次投递记录，可按轮次筛选并查看 HTTP 状态、响应文本、耗时及错误。

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

请求地址

GET /open/v1/webhooks/{id}/attempts

鉴权请求头

先获取 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，规范正整数十进制字符串，范围 1–9223372036854775807；不接受前导零、加号、空白或小数。	123456789012345680

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

Query 参数

字段	类型	必填	说明	示例值
page	integer（Query 字符串）	否	页码，默认 1，最小为 1；空值按默认值处理。当前服务要求 page × page_size 不超过 9223372036854775807。	1
page_size	integer（Query 字符串）	否	每页数量，默认 20，范围 1–100；空值按默认值处理。	20
round_id	string	否	只查询此轮次；必须且只能出现一次，格式为规范正 int64 字符串。不传则查询事件全部轮次；传空字符串非法。	123456789012345681

round_id 必须属于路径指定的事件，否则返回 404。它是投递轮次里的 id，不是 round_no。仅接受表中参数，不接受 status、时间或其他业务筛选；未知字段和重复 Query 键均返回 400。记录按尝试 id DESC 排序；total 是应用 round_id 条件后的尝试总数。

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

GET /open/v1/webhooks/123456789012345680/attempts?page=1&page_size=20&round_id=123456789012345681

成功响应

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。	123456789012345682
event_id	string	是	所属回调事件 ID。	123456789012345680
round_id	string	是	所属轮次的 ID，可用于 round_id 筛选。	123456789012345681
round_no	integer	是	所属轮次编号，从 1 开始。	2
attempt	integer	是	本轮内的尝试编号，1–20；新轮次从 1 重新计数。	1
status	string	是	尝试状态：sending / succeeded / failed / unknown；与事件和轮次的状态枚举不同。	succeeded
http_status	integer 或 null	是	接收端 HTTP 状态码；没有取得响应或结果未知时为 null。	200
error	string	是	此次尝试的错误说明；没有错误时为空字符串。	""
started_at	string	是	尝试开始时间，RFC 3339 带时区。	2026-09-08T00:20:00Z
finished_at	string 或 null	是	尝试结束或恢复时标记结束的时间；sending 时为 null。	2026-09-08T00:20:02Z
duration_ms	integer 或 null	是	已知完成结果的耗时，单位毫秒；sending 或中断后 unknown 可为 null。	2000
response_body	string	是	接收端响应的展示文本，最多 65536 UTF-8 字节；没有响应为空字符串，可能被清理或截断。	{"code":"SUCCESS"}
response_truncated	boolean	是	正文超限或清理后超限而截断时为 true。	false
created_at	string	是	尝试记录创建时间，RFC 3339 带时区。	2026-09-08T00:20:00Z

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "id": "123456789012345682",
        "event_id": "123456789012345680",
        "round_id": "123456789012345681",
        "round_no": 2,
        "attempt": 1,
        "status": "succeeded",
        "http_status": 200,
        "error": "",
        "started_at": "2026-09-08T00:20:00Z",
        "finished_at": "2026-09-08T00:20:02Z",
        "duration_ms": 2000,
        "response_body": "{\"code\":\"SUCCESS\"}",
        "response_truncated": false,
        "created_at": "2026-09-08T00:20:00Z",
        "network": "nile"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

状态与空值

status 的四种取值为 sending（进行中）、succeeded（取得有效成功应答）、failed（本次失败）和 unknown（请求中断后无法确认投递结果）。一次尝试失败不等于整个轮次已经失败，后续仍可能自动重试。

sending 通常有 http_status: null、finished_at: null、duration_ms: null。网络错误未取得 HTTP 响应时，完成后 http_status 仍可为 null。恢复后标记 unknown 的尝试可以有 finished_at，而 duration_ms 仍为 null，例如：

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "id": "123456789012345683",
        "event_id": "123456789012345680",
        "round_id": "123456789012345681",
        "round_no": 2,
        "attempt": 2,
        "status": "unknown",
        "http_status": null,
        "error": "delivery result unknown after notifier interruption",
        "started_at": "2026-09-08T00:20:30Z",
        "finished_at": "2026-09-08T00:20:46Z",
        "duration_ms": null,
        "response_body": "",
        "response_truncated": false,
        "created_at": "2026-09-08T00:20:30Z",
        "network": "nile"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

响应保存与成功判定

response_body 最多保存 64 KiB（65536 字节）的 UTF-8 展示文本。无效 UTF-8 会替换，NUL 会转为可见转义文本；原始响应或清理后的文本超限时会截断，response_truncated 为 true，并判定本次失败。此字段可能不是完整 JSON，也不保证与原响应逐字节相同。

有效成功应答必须为 HTTP 200，正文为完整、合法的 UTF-8 JSON 对象，其中 code 的值为大小写精确的字符串 "SUCCESS"。允许其他字段；重复键、尾随数据、超过 64 KiB、读取失败、其他 HTTP 状态和其他 code 均不算成功。详情见回调通知指南。

次数按尝试记录计数。结果未知的 unknown 也会占用本轮次数；不能假定接收端一定看到了每一条尝试。若未配置或关闭回调，事件可能直接失败而没有尝试记录，此时 items 为 []、total 为 0。

典型错误

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

事件 ID、round_id 或分页格式/范围非法，以及 round_id 重复出现，均返回 HTTP 400。事件不存在、不属于当前账户和网络，或指定轮次不属于该事件时返回 HTTP 404。

HTTP 400：round_id 不是规范正整数

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

HTTP 400：重复提供 round_id

{
  "code": 400,
  "message": "duplicate query parameter",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 400：分页超出范围

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

HTTP 404：事件不可见或指定轮次不属于该事件

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

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

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

完整字段与状态

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