重新推送回调
为当前账户和网络下已经失败的回调事件新建投递轮次，保留原事件 ID、业务 payload 和历史记录。
本页 ID、地址、URL、交易哈希、金额和时间均为文档示例，请替换成自己账户的数据。所有 ID 和金额使用字符串；计数、页码与 HTTP 状态码使用 JSON 数值。金额使用六位精度最小单位字符串，例如 "100000000" 表示 100 USDT，"1000000" SUN 表示 1 TRX。
请求地址
http
POST /open/v1/webhooks/{id}/redeliver鉴权请求头
先获取 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> |
| Content-Type | string | 是 | 请求体为单个 UTF-8 JSON 对象，可指定 charset=utf-8。 | application/json |
路径参数
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| id | string | 是 | 回调事件 ID，规范正整数十进制字符串，范围 1–9223372036854775807；不接受前导零、加号、空白或小数。 | 123456789012345680 |
事件必须属于当前账户和当前网络；不存在、其他账户或其他网络的事件统一返回 404。
请求体
请求体必须是单个 JSON 对象，仅提供 request_id。不接收新的 URL、payload、轮次 ID 或 MFA 验证码；URL 来自当前回调配置。不要发送 Idempotency-Key 请求头。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| request_id | string | 是 | 本操作的幂等编号，16–128 个 UTF-8 字节；同一业务请求重试时保持不变，仅放 JSON body。 | webhook-redeliver-example-20260908-0001 |
URL 不接受任何 Query，包括尾随的 ?；所有业务字段只能放 JSON body。路径中的 id 决定重推的事件。
http
POST /open/v1/webhooks/123456789012345680/redeliverjson
{
"request_id": "webhook-redeliver-example-20260908-0001"
}成功响应
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 完整字段
返回此次新建轮次的完整对象，共 11 个字段。这是业务受理结果，真正的 HTTP 投递由后台执行。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| 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 | 是 | 本轮最近错误；没有错误时为空字符串。 | "" |
json
{
"code": 0,
"message": "",
"data": {
"network": "nile",
"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": ""
}
}回调未配置或已停用也可能返回 HTTP 200
新轮次读取当前回调 URL 和开启状态；未配置或已停用时，仍创建并保存新轮次，但它立即处于 failed，attempts 为 0、finished_at 有值、next_attempt 为 null。应同时检查 data.status 和 data.last_error，不能把 HTTP 200 理解为通知已送达。
json
{
"code": 0,
"message": "",
"data": {
"network": "nile",
"id": "123456789012345681",
"event_id": "123456789012345680",
"round_no": 2,
"url": "",
"started_at": "2026-09-08T00:20:00Z",
"deadline_at": "2026-09-08T00:30:00Z",
"finished_at": "2026-09-08T00:20:00Z",
"attempts": 0,
"next_attempt": null,
"status": "failed",
"last_error": "callback URL is not configured"
}
}未配置时 last_error 为 callback URL is not configured，URL 可为空；已配置但停用时为 callback is disabled，URL 保留本轮读取的值。解决配置问题后，使用新的 request_id 才会发起另一轮。
重推条件与幂等
仅当前投递状态为 failed 的事件可以新建轮次。pending、delivering 或 delivered 的事件返回 HTTP 409。新轮次编号递增，尝试次数从 0 开始，重新获得 10 分钟和最多 20 次额度；事件 ID 和 payload 保持不变，已有轮次及尝试历史完整保留。新轮次固定当前 URL，之后修改配置不会改变已创建轮次的 URL。
同一账户、同一操作下，相同 request_id 和相同事件参数返回首次保存的完整响应，不会再次增加轮次；相同 request_id 换成其他事件参数返回 HTTP 409。请求超时或断线后重试，请保留原 request_id，并为新 HTTP 请求重新生成时间戳和签名。
幂等重放返回首次结果快照；即使轮次后来已经投递成功，重放响应也可能仍是首次的 pending。用回调详情、投递轮次和投递尝试读取最新状态。已成功保存的同键请求重放，不会因为当前事件状态已经变化而新建轮次。
每轮最长 10 分钟、最多 20 次尝试；正常重试的实际请求开始时间至少间隔 30 秒。单次请求最长 15 秒，且不能超过本轮截止时间。尝试失败后，轮次可能继续等待重试；只有成功、期限到达或次数耗尽等结束条件才终结该轮次。
典型错误
错误响应不含 data；鉴权、账户状态、限流和超时等通用错误见通用错误说明。
事件 ID 或 request_id 非法、request_id 不是 JSON 字符串/只放在 Query、出现额外业务字段时返回 HTTP 400。事件不存在或不属于当前账户和网络时返回 HTTP 404。事件尚未失败，或幂等编号已用于其他参数时返回 HTTP 409。
HTTP 400：request_id 缺失、类型错误或字节长度不合要求
json
{
"code": 400,
"message": "request_id requires 16..128 characters",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 400：请求 URL 带有 Query
json
{
"code": 400,
"message": "this operation accepts parameters only in its JSON body",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}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 409：事件当前状态不是 failed
json
{
"code": 409,
"message": "only failed notifications can start a new delivery round",
"error_code": "BUSINESS_CONFLICT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 409：同一幂等编号已用于不同事件或网络参数
json
{
"code": 409,
"message": "conflict: idempotency key already used with another request",
"error_code": "IDEMPOTENCY_CONFLICT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 401：token 缺失、无效或已过期
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。