Webhook 验签、重试与去重
配置事件接收端，验证真实事件，并处理排队、重试或过期的投递。
- 适用对象
- 管理员
- 内容更新
- 2026-09-09
先登录公司系统；文中的 /app/… 是加在公司系统网址后的页面路径。
开始前
- 使用你自己的部署域名或接收端域名的公网 HTTPS 接收地址
- 运行时开关已启用；池化部署还需要 Max 或 Enterprise 权益
- 执行对应操作所需的 integration.manage 权限：读取用 view，创建/编辑/测试/重试/轮换用 edit，删除用 delete
- 可持久保存 event ID，以及由接收端配置的时间戳容差
操作步骤
创建事件接收端
打开你自己的部署域名下的 /app/int/docs?section=webhooks&lang=zh 或 /app/int/docs?section=webhooks&lang=en，再进入“开发者中心 → Webhook”。填写名称和公网 HTTPS 地址，只选择需要的事件后创建接收端。真实事件目录是 customer.created、customer.updated、conversation.created、conversation.assigned、conversation.status_changed、message.created 和 message.delivery_updated。
预期结果: 接收端只订阅当前租户所选的事件。
保存 Secret 并验证原始字节
Secret 只显示一次，请立即保存。在解析 JSON 前，对 timestamp + “.” + 完整原始请求字节计算 HMAC SHA256。只有 X-AOS-Signature 使用恒定时间比较；按接收端容差验证时间戳年龄，再按 X-AOS-Event-Id 持久去重。发送方会在设置时拒绝不安全的接收端地址。
预期结果: 验签与时间戳检查用于拒绝无效请求；接收端实现持久去重后才能避免重复处理。
发送测试并查看投递记录
创建或编辑接收端后使用“发送测试”。测试类型是 webhook.test，数据为 {test:true}，只发送到当前选择的接收端。HTTP 202 仅表示已排队；投递记录中的实际 2xx 才表示接收成功。事件持久接受后要尽快返回 2xx，并按 event ID 去重。
预期结果: 你能区分排队接受与接收成功，并避免重复处理。
处理重试与人工恢复
网络错误、408、425、429 和 5xx 会自动重试，其他 4xx 终止；总共最多尝试七次。人工重试保留原 event ID，只有投递失败、已尝试次数少于七次、载荷仍有效且接收端启用时才允许。次数耗尽、已取消或已过期的记录不能重试。较早的重试可能晚于更新事件到达。
预期结果: 接收端按 event ID 和事件顺序规则安全处理重试。
有计划地轮换或停用
密钥轮换期间，旧 Secret 和新 Secret 的双签名重叠期为 24 小时；之后再移除接收端的旧 Secret。停用、删除或权益撤回会取消待投递积压；重新启用不会补发停用期间事件。事件载荷保留七天，投递记录保留 30 天。
预期结果: 轮换与生命周期变化不会产生意外补发，并有明确保留期限。