Webhook 重复投递导致订单重复处理怎么防

现象#

同一笔订单被创建了两条内部记录，或库存被扣两次；日志里同一个 X-Shopify-Webhook-Id 出现多次。

原因#

• 服务端处理超时或返回非 2xx，Shopify 按重试策略再次投递
• 网关超时但业务已执行，重试时没有幂等判断
• 同一 topic 订阅了多个地址，逻辑各自执行一遍

处理步骤#

1. 用 X-Shopify-Webhook-Id 做幂等键，处理前先查是否已消费，处理中加锁
2. 收到请求后立即返回 200，把耗时逻辑放进队列异步执行
3. 数据库对业务主键加唯一约束，重复写入直接失败并吞掉异常
4. 核对应用与后台的订阅列表，删除指向同一逻辑的重复订阅

验收标准#

人为重放同一 webhook 三次，业务只执行一次；订单与库存数据无重复。