Webhook Duplicate Events（Webhook 事件重复）

知识库位置：FDE Knowledge Base/03 Engineering/Troubleshooting/Webhook-Duplicate-Events.md

Problem（问题）

同一个 Webhook（Web 回调）被发送多次，导致业务动作重复。

例如：

PaymentCompleted（支付完成）

被处理两次，产生两张发票。

Important Principle（重要原则）

Webhook Provider（提供方）通常只保证：

At-least-once delivery（至少一次投递）

这意味着：

重复是正常情况，不是异常情况。

Root Cause（根本原因）

典型流程：

Provider（提供方）
↓
Webhook（Web 回调）
↓
Consumer processes successfully（消费方处理成功）
↓
Response delayed（响应延迟）
↓
Provider thinks failed（提供方认为失败）
↓
Retry（重试）

于是同一个 Event（事件）再次发送。

Correct Design：Idempotency（正确设计：幂等性）

每个 Event 应有唯一 ID：

event_id = evt_12345（事件 ID = evt_12345）

处理前：

Have we processed evt_12345?（是否已处理过 evt_12345）

如果是：

Ignore safely.（安全忽略）

Better Pattern（更好的模式）

Receive Webhook（接收回调）
↓
Validate Signature（校验签名）
↓
Check Event ID（检查事件 ID）
↓
Persist Event（持久化事件）
↓
Return 2xx Quickly（快速返回 2xx）
↓
Async Processing（异步处理）

不要在 Webhook Request（回调请求）中执行非常耗时的业务逻辑。

Also Consider（还需考虑）

Ordering（事件顺序）

事件可能顺序错乱：

OrderShipped（订单已发货）

可能比：

OrderPaid（订单已支付）

先到。

因此不要完全依赖到达顺序。

Prevention（预防）

必须有：

Event ID（事件 ID）
Deduplication（去重）
Idempotent Business Action（幂等业务动作）
Retry-safe Processing（重试安全的处理）
Event Log（事件日志）