Webhook 重复触发时该怎么办：AI Agent 的幂等性、去重与补偿设计
将 Webhook 与 AI Agent 集成后，最难排查的故障往往不是事件丢失，而是同一事件被处理了两次：客户收到重复消息、创建了两份工单、库存被反复扣减，且每次重试都会让定时任务越来越混乱。发送方重试、网络超时和消费者崩溃都可能导致回调重复。正确的目标不是要求 Webhook 永不重复，而是确保重复事件不会产生第二次业务结果。
首先，定位重复发生的层级
首先记录事件 ID、来源、接收时间、请求体摘要、处理状态和外部操作回执。如果两个请求具有相同的事件 ID，通常是发送方进行了重试。如果事件 ID 不同但业务对象相同，上游系统可能多次生成了该事件。如果只收到一次请求却产生了两个结果，需排查消费者内部的重试或并发执行问题。缺乏这些证据就匆忙禁用重试，只会将“重复事件”变成“丢失事件”。
使用幂等键阻止二次业务写入
优先使用发送方提供的稳定事件 ID。如果没有事件 ID，可通过组合来源、事件类型、业务对象 ID 和版本号来生成幂等键。不要简单地对整个请求体进行哈希：时间戳、字段顺序或签名的变化会导致同一业务事件产生不同的哈希值。
数据库应对幂等键强制执行唯一约束。处理开始时，先原子性地插入一条“处理中”记录。若发生冲突，读取之前状态：若已成功，则返回原始结果；若仍在处理中，可短暂等待或返回可重试状态；若已失败，则按既定策略重试。仅在内存中维护去重集是不可靠的，因为进程重启或多实例并发时会失效。
幂等记录至少应包含的字段
| 字段 | 用途 | 验收标准 |
|---|---|---|
| 幂等键 | 标识同一事件 | 强制执行唯一约束 |
| 处理状态 | 区分处理中、成功和失败 | 状态变更可追溯 |
| 结果摘要 | 为重复请求复用历史结果 | 不再调用外部系统 |
| 过期时间 | 控制去重窗口 | 长于发送方的最大重试周期 |
将回执确认与实际执行分离
Webhook 端点应在返回确认前快速完成签名验证、幂等注册和队列插入。耗时的模型调用、文件处理和跨系统写入应由后台任务处理。这降低了因响应超时而导致发送方重试的概率，也便于控制并发。有关 API、Webhook 和技能之间的边界划分，请参阅AI Agent 与现有工具集成指南。
单独防止外部操作重复
成功对事件去重并不意味着后续操作天然安全。发送消息、创建订单和写入工单等操作都应拥有独立的操作键，并保存目标系统返回的 ID。如果任务在外部操作成功后、内部状态持久化前崩溃，应在恢复期间查询回执，再决定是持久化缺失状态还是重新执行操作。直接重跑整个链路是最危险的做法。
如何划分重试、补偿与死信队列的职责
网络不稳定、速率限制和临时 5xx 错误可通过指数退避重试和最大尝试次数限制来处理。确定性失败（如参数无效或权限不足）不应反复重试。如果在部分步骤成功后发生错误，应执行明确的补偿动作或将事件发送给人工核验。超出重试预算的事件应进入死信队列，保留原始载荷、失败步骤和回执。如需更完整的恢复策略，请参阅AI Agent 工作流监控与恢复指南。
上线前运行四项故障注入演练
- 连续发送两次相同事件，确认仅产生一项业务结果。
- 让两个消费者同时认领同一事件，确认唯一约束能阻止并发写入。
- 强制在外部操作成功后中断，验证恢复期间能否复用其回执。
- 模拟速率限制、超时和永久错误，检查重试预算和死信记录。
日志应将事件 ID、幂等键、任务 ID 和外部回执关联起来。如果问题仍难以定位，请继续参考AI Agent 端到端追踪清单。
常见问题
返回 200 后 Webhook 还会重试吗？
取决于发送方的协议。某些平台可能因连接中断、非合规响应体或内部投递策略而继续重试，因此消费者仍需实现幂等性。
去重窗口应设置多长？
至少应覆盖发送方声明的最大重试周期。涉及订单、支付或工单的事件通常需要保留更长时间，以满足业务追溯要求。
Redis SETNX 足够了吗？
适用于抢占处理权，但必须考虑过期时间、任务崩溃、结果持久化和多步外部操作。关键业务流程通常需以数据库唯一约束作为兜底保障。
可以直接丢弃重复事件吗？
对于已成功处理的事件，可返回历史结果。对于仍在处理中或状态未知的事件，不应盲目丢弃；应查询其状态或发送至核验队列。
将重复回调转化为可验证的正常状态
Webhook 的可靠性源于“允许重复，但结果仅生效一次”。首先建立稳定的幂等键，然后将回执与执行分离，并为每项外部操作保存回执。SmaugBrain 可将去重、后台执行、故障恢复和验收步骤组织为可持续运行的 Agent 工作流。访问 SmaugBrain，从低风险回调的试运行开始。