Webhook 投递与重发
本页说明 webhook 投递失败时 QI Tech 的处理方式，以及用于查询投递记录和手动重发的端点。事件列表请参见 书写事件；配置接收地址请参见 Webhook 配置。
每个事件在投递前都会被记录。首次投递是同步的，在事件生成的同一时刻发出；若失败，该事件进入重发队列。
重发策略
当您的端点返回 3xx、4xx 或 5xx 状态，或请求完全没有得到响应（DNS 失败、连接被拒绝或超时）时，该次投递视为失败。
每个事件最多投递 8 次：首次投递加 7 次重发，两次之间的间隔逐次递增。
| 尝试次数 | 距上次 的间隔 | 距首次的时间 |
|---|---|---|
| 1 | — | 0 |
| 2 | 1 分钟 | 1 分钟 |
| 3 | 5 分钟 | 6 分钟 |
| 4 | 15 分钟 | 21 分钟 |
| 5 | 1 小时 | 1 小时 21 分 |
| 6 | 3 小时 | 4 小时 21 分 |
| 7 | 6 小时 | 10 小时 21 分 |
| 8 | 12 小时 | 22 小时 21 分 |
8 次尝试用尽后，事件状态变为 failed，不再发送。
重发队列每 5 分钟处理一次，因此实际间隔可能比表中数值最多长 5 分钟。
如果您的系统已处理该事件，但响应未能到达我们这边（例如超时，或处理之后发生错误），该次投递将被计为失败，事件会被重新发送。
每次尝试的请求体完全相同。event_datetime 记录的是事件生成的时刻，而非发送时刻，因此在各次尝试之间不会变化：请使用 event_type、event_datetime 以及 event_data 中的标识符组合，来识别已经处理过的事件。
Webhook 状态
| 状态 | 描述 |
|---|---|
pending_shipment | 上次投递失败。next_attempt_at 字段表示下次尝试的时间。 |
on_queue | 重发已入队，等待处理。 |
sent | 已送达。您的端点返回了 2xx。 |
failed | 8 次尝试已用尽，事件不再发送。 |
查询 Webhook 列表 (GET)
返回您 tenant 的事件，按时间从新到旧排列。可用于核对 QI Tech 已发送的内容与您系统已处理的内容。
Request
Query Params
| 字段 | 类型 | 描述 |
|---|---|---|
status | string | 按投递状态过滤。可取 pending_shipment、on_queue、sent 或 failed。 |
event_type | string | 按事件类型过滤，例如 commercial_paper.operation_status_change。 |
created_after | string | 返回自该时间起生成的事件，格式为 YYYY-MM-DDTHH:MM:SS。 |
created_before | string | 返回截至该时间生成的事件，格式同上。 |
page | integer | 页码，从 1 开始。默认 1。 |
page_size | integer | 每页记录数。默认值与最大值均为 100。 |
Response
Response Body
{
"data": [
{
"webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"status": "pending_shipment",
"number_of_attempts": 2,
"next_attempt_at": "2026-05-05T13:27:01",
"webhook_data": {
"event_type": "commercial_paper.operation_status_change",
"event_datetime": "2026-05-05T13:22:01Z",
"event_data": {
"operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
"operation_status": "issued"
}
},
"created_at": "2026-05-05T13:22:01"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
Response Body Params
| 字段 | 类型 | 描述 |
|---|---|---|
webhook_key | string | 事件的唯一键（UUID v4），也是手动重发时使用的标识。 |
tenant_key | string | 该事件所属 tenant 的键。 |
status | string | 当前投递状态。status 枚举值 |
number_of_attempts | integer | 已失败的投递次数。成功的投递不会增加该计数。 |
next_attempt_at | string | 下次重发的时间。没有计划中的重发时为 null。 |
webhook_data | object | 发送到您端点的请求体，与实际投递内容一致。 |
created_at | string | 事件生成的时间。 |
查询单个 Webhook (GET)
Request
Path Params
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
WEBHOOK-KEY | string | 事件的唯一键（UUID v4）。 | 36 |
Response
Response Body
{
"webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"status": "pending_shipment",
"number_of_attempts": 2,
"next_attempt_at": "2026-05-05T13:27:01",
"webhook_data": {
"event_type": "commercial_paper.operation_status_change",
"event_datetime": "2026-05-05T13:22:01Z",
"event_data": {
"operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
"operation_status": "issued"
}
},
"created_at": "2026-05-05T13:22:01"
}
字段含义与 Response Body Params 中描述的相同。
手动重发 (PUT)
立即发送该事件，无需等待重发策略的下一个窗口。适用于您的系统已恢复、但下一次重发间隔尚未到达的情况。
手动尝试遵循与自动重发相同的规则：失败时计数加一并安排下一个间隔；第 8 次失败后，事件状态变为 failed。
只有处于 pending_shipment 或 on_queue 的事件可以重发。
Request
Path Params
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
WEBHOOK-KEY | string | 事件的唯一键（UUID v4）。 | 36 |
Response
响应没有 body。202 仅确认本次尝试已执行，并不代表您的端点已接受：请查询该事件以确认结果。
错误
| HTTP 状态码 | 错误码 | 描述 (eng) | 翻译 (pt-BR) |
|---|---|---|---|
| 404 | OWB0000001 | Webhook not found. | Webhook não encontrado. |
| 400 | OWB0000005 | You do not have access to this tenant. | Você não tem acesso a este tenant. |
| 409 | OWB0000007 | Webhook is {webhook_status} and cannot be sent again. | O webhook está {webhook_status} e não pode ser reenviado. |
| 409 | OWB0000008 | Webhook is already being sent by another process. | O webhook já est á sendo enviado por outro processo. |