Webhook 与事件恢复

第 1 步 — 配置接收目标

管理员在 API 与集成 中展开某把 API 密钥并添加 HTTP 或 HTTPS 目标。建议使用 HTTPS；界面会对 HTTP、直接 IP 和本地地址给出警告，但不会阻止保存。只有中间件能够访问该 URL 时，事件才可成功送达。每个目标属于对应密钥，并有独立签名密钥；完整密钥只在创建或轮换时显示。接收端只需要部分事件时，可选择具体类型。轮换或撤销 API 密钥也会影响关联目标，因此请先准备好接收端再启用投递。

“接收端就绪”仅表示目标 URL 和签名密钥已经配置，不表示已经收到事件。日志与监控中应区分三类流量：向外发送的 API 命令、传入的 Webhook 投递，以及 GET /v1/events 恢复。由你的后端发起的 PUT 或 POST 不是收到的 Webhook。

确认配对时，请核对 API 密钥页面显示的完整目标 URL 与接收端实际 URL，并保存该目标返回的签名密钥。API 之后不会再次显示完整密钥。只有传入的签名 POST 验证成功后，才应声明收到实时事件；本地保存了密钥只能证明配置已准备好。

第 2 步 — 先验证，再处理

每次投递包含 webhook-id、webhook-timestamp 和 webhook-signature。签名遵循 Standard Webhooks：对 webhook-id + "." + webhook-timestamp + "." 的 UTF-8 字节，再拼接未经修改的原始请求体字节，使用 HMAC-SHA256。签名密钥以 whsec_ 开头，其中包含 Base64 编码的密钥。请使用常量时间比较某个 v1, 项的 Base64 签名。

服务器时间相差超过五分钟的请求应被拒绝。必须在解析 JSON 前验证签名。随后确认事件正文中的 id 等于 webhook-id，并在产生业务副作用前保存该 ID。接收端应尽快返回成功的 2xx。

投递语义为 at least once，顺序也不保证。按事件 ID 去重。完成事件仅携带标识符和 API 路径；需要完整数据时，通过已验证 API 读取当前报告或档案。主要完成事件为 rental.departure.completed 和 rental.return.completed，报告更正与 PDF 就绪使用不同事件。全部字段见 Rental OpenAPI 定义。

第 3 步 — 每个信号之后重新对账

收到有效完成事件后，通过已验证 API 重新读取 Rental 或报告索引。JSON 可能先于 PDF 就绪；按照报告与原始凭证中的 200/202 流程处理。不要让业务流程无限等待 Webhook；即使接收端健康，定期对账仍然有效。

第 4 步 — 恢复遗漏事件

中断恢复后，使用带 cursor 和可选 created_after 的 GET /v1/events。事件保留 30 天。只有处理完当前页，才推进已保存的 cursor。接收端不可用时，平台会在 48 小时内最多重试八次；管理员可在 API 与集成 中查看并重试最近失败的投递。

事件流只是通知，当前数据始终以已验证资源路由为准。报告标识与版本说明如何安全归档结果。

没有收到签名事件时

确认目标、API 密钥和环境与发出 API 请求时完全一致。
确认已选择 rental.departure.completed 和 rental.return.completed，并核对完整 URL。
查看投递历史。非 2xx、超时或签名被拒绝属于接收端故障；停用或撤销的密钥应先修复。
立即运行 GET /v1/events，在修复投递期间继续处理业务。
只有接收端已经丢失对应密钥时才轮换签名密钥，并在重试前更新接收端。

升级给支持团队时，请提供事件或投递 ID 以及 API request_id，切勿发送签名密钥。