回调投递轮次

分页查询一个回调事件的全部投递轮次，包括固定 URL、时间窗口、尝试次数和终止原因。

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

请求地址

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

鉴权请求头

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

仅接受表中分页参数；未知字段和重复 Query 键均返回 400。记录按轮次 id DESC 排序；total 是该事件的轮次数。只有一个初始轮次时也返回分页对象。

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

GET /open/v1/webhooks/123456789012345680/rounds?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；与 round_no 的编号含义不同。第一轮 ID 当前与事件 ID 相同，新轮次使用新的 ID。	123456789012345681
event_id	string	是	所属回调事件 ID，各轮次保持一致。	123456789012345680
round_no	integer	是	此事件的轮次编号，从 1 开始。	2
url	string	是	本轮固定的回调 URL 快照；未配置时可为空字符串。	https://merchant.example.com/guiji/webhook
started_at	string	是	本轮开始时间，RFC 3339 带时区。	2026-09-08T00:20:00Z
deadline_at	string	是	本轮开始时间加 10 分钟，RFC 3339 带时区。	2026-09-08T00:30:00Z
finished_at	string 或 null	是	本轮结束时间；pending / delivering 为 null，delivered / failed 为带时区时间。	null
attempts	integer	是	本轮已开始的尝试次数，0–20。	0
next_attempt	string 或 null	是	本轮下次尝试时间；pending / delivering 有值，delivered / failed 为 null。	2026-09-08T00:20:00Z
status	string	是	轮次状态：pending / delivering / delivered / failed。	pending
last_error	string	是	本轮最近错误；没有错误时为空字符串。	""

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "id": "123456789012345681",
        "event_id": "123456789012345680",
        "round_no": 2,
        "url": "https://merchant.example.com/guiji/webhook",
        "started_at": "2026-09-08T00:20:00Z",
        "deadline_at": "2026-09-08T00:30:00Z",
        "finished_at": null,
        "attempts": 0,
        "next_attempt": "2026-09-08T00:20:00Z",
        "status": "pending",
        "last_error": "",
        "network": "nile"
      },
      {
        "id": "123456789012345680",
        "event_id": "123456789012345680",
        "round_no": 1,
        "url": "",
        "started_at": "2026-09-08T00:00:00Z",
        "deadline_at": "2026-09-08T00:10:00Z",
        "finished_at": "2026-09-08T00:00:00Z",
        "attempts": 0,
        "next_attempt": null,
        "status": "failed",
        "last_error": "callback URL is not configured",
        "network": "nile"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

pending 和 delivering 的 finished_at 为 null、next_attempt 有值；delivered 和 failed 的 finished_at 有值、next_attempt 为 null。last_error 和 url 可以为空字符串，但不为 null。

每轮最长 10 分钟、最多 20 次尝试；正常重试的实际请求开始时间至少间隔 30 秒。单次请求最长 15 秒，且不能超过本轮截止时间。尝试失败后，轮次可能继续等待重试；只有成功、期限到达或次数耗尽等结束条件才终结该轮次。

每轮固定自己的回调 URL。初始轮次在事件入库时创建；重推仅为失败事件新建轮次，读取当前回调 URL，保留旧轮次和相同事件 payload。回调未配置或已停用时，轮次可以直接为 failed，attempts 为 0，未发送任何 HTTP 请求。

用轮次 id 作为 投递尝试的 round_id 可查看该轮逐次结果；不要使用 round_no 代替 round_id。本页不返回各次 HTTP 状态或响应正文。

典型错误

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

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

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

{
  "code": 400,
  "message": "id must be a positive integer string",
  "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"
}

完整字段与状态

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