# 接收回调

登记回调地址后，任务结束和费用结算时我们向它发送签名的通知。

回调让你不用一直轮询：任务结束时我们向你登记的 HTTPS 地址发送 `POST` 请求。

## 登记地址

1. 在控制台的「[回调](./callbacks.html)」页添加 HTTPS 地址并完成验证，保存登记时显示的签名密钥 `signing_secret`。
2. 创建任务时在请求体里写 `callback_url`，值必须与本团队已验证、未撤销且未过期的地址逐字节相同，否则返回 `400 callback_target_not_verified`。
3. 收到通知时先[验证签名](./api-docs-zh-callbacks-verify.md)，再处理正文。

## 两种事件

| 事件 | 什么时候发送 |
| --- | --- |
| [`task.completed`](./api-docs-zh-api-events-task-completed.md) | 任务成功、失败或取消之后；成功的任务要先完成交付处理。 |
| [`task.billing_settled`](./api-docs-zh-api-events-task-billing-settled.md) | `task.completed` 已送达或放弃、且费用结算确定之后。完成后三十天仍未结算的任务不发送。 |

两个事件的正文都是任务快照，不含结果下载地址；需要下载时再查询任务。

## 响应与重试

只有 2xx 响应表示已收到。其他状态或超时会重试：第一次失败后依次等待 10 秒、1 分钟、5 分钟，之后每小时一次，每个事件最长 7 天。`task.billing_settled` 的 7 天从它自己开始投递时算起。

## 去重

每个事件至少送达一次，可能重复。验证签名后，按正文里的 `event_id` 去重；请求头 `Chenvoya-Event-Id` 没有被签名，只是方便查看的副本。处理过的事件 ID 至少保存 7 天零 5 分钟。重试时事件 ID 和正文的原始字节都不变。

## 撤销地址

在控制台撤销地址后不再开始新的投递，但已经开始发送的那一次仍可能到达。控制台可以查看通知记录；任务的当前状态和下载结果始终以查询任务为准。

## 下一步

- [验证回调签名](./api-docs-zh-callbacks-verify.md)：用登记地址时拿到的签名密钥，验证每个通知确实来自我们。
- [接收任务完成通知](./api-docs-zh-api-events-task-completed.md)：任务进入成功、失败或取消终态后发送 task.completed；成功任务须已完成交付处理。
- [接收任务结算通知](./api-docs-zh-api-events-task-billing-settled.md)：task.completed 已送达或放弃且任务结算为 settled 或 settled_with_receivable 后，发送 task.billing_settled，使用独立的七天投递窗口。