Webhook 幂等与重试:去重键、保留期和副作用怎么放
直接回答: 多数发送方在超时、5xx 和网络抖动时会重试,少数要你自己重投,所以按至少一次来接:每个事件定一个稳定的键,副作用之前先把处理状态落库,去重记录至少保留到对方最长的重试时长。已完成的键直接回 2xx。
1.0 发送方会重试,接收方只能按至少一次来设计
你这边超时的那个 webhook,可能其实已经处理完了。发送方不知道,于是重试。返回 500、网络直接断掉,结果也一样。按”每个事件只来一次”去写代码,迟早会出现重复邮件、库存扣两次,或者一笔付款生成两张 ERP 单据。
各家重试多久并不一样。以 Stripe 为例,线上环境的 webhook 投递会以指数退避重试,最长三天;GitHub 不会自动重投失败的投递,只能在界面或 API 里手动重投最近 3 天的记录。先读对方关于重试和重推的说明,按你在意的最长窗口来定去重保留期。“我们响应快,对方不会重试”这种估计靠不住。
2.0 选一个稳定的键
| 来源 | 常见的键 | 说明 |
|---|---|---|
| 提供方事件 ID | evt_…、投递 GUID | 如果它对每个逻辑事件唯一,优先用它 |
| 组合键 | (provider, event_id) | 同一个系统接多家的 webhook 时用 |
| 请求头 | Idempotency-Key、X-GitHub-Delivery | Idempotency-Key 用于你自己对外的 API;GitHub 重投时 X-GitHub-Delivery 与原投递相同,标识的是事件而不是某一次投递 |
| 业务对象 | (event_type, object_id) | 提供方可能为同一个底层变化发出两个 Event 对象时需要 |
键上加唯一约束,或者用原子的条件写入。难的是并发:两个 worker 可能同时查到”不存在”,所以插入这一下本身就得是闸门,先查后插不算数。
3.0 记状态,不要只记“做完没”
| 状态 | 含义 | 同一个键又来一次时 |
|---|---|---|
| processing | 已接收,正在处理(可带租约 / 持有者) | 等待、返回冲突,或挂到正在进行的那次上——不要再起第二条副作用路径 |
| completed | 已落库,副作用已完成 | 直接回 2xx,不做副作用 |
| failed_retryable | 可恢复的失败,重试安全 | 按退避重试,仍用同一个键 |
| failed_terminal | 没人介入就不会成功 | 告警,别让它无限自动循环 |
processing 要在第一次接收这个键的那次持久写入里一起标上,发生在任何邮件、扣款或 ERP 调用之前。completed 要等这些副作用各自有了持久记录才标(或者等驱动它们的 outbox 行已经提交)。
4.0 重试窗口和去重保留期
有两个时长必须对齐:
- 发送方重试窗口:提供方(或你自己的重推脚本)在多长时间内还可能把同一个事件再发一次。
- 接收方去重保留期:键和处理结果留多久,晚到的重复才认得出来。
保留期必须 ≥ 你接受的重试窗口。键过期得早,晚到的重试看起来就是新事件。手动重推能追溯得更远:Stripe 自动重试最长三天,但在 Dashboard 里可以重发 15 天内的事件,用 CLI 可以重发 30 天内的。如果运维在保留期过后还会从控制台重推,要么把保留期拉长,要么要求换新键,并走明确的对账流程。
5.0 先落库,再确认
最麻烦的是这种情况:处理函数已经把活干完,连接却在发送方收到 2xx 之前断了。发送方重试。如果”已成功”只记在内存里,副作用就会再跑一遍。
我们的做法:
- 先写事件(或 outbox 行)和 processing / completed 状态。
- 这次写入提交之后才回 2xx。
- 非幂等的副作用从持久记录出发,放在去重之后执行。
- 副作用慢的话,持久接收后就先确认,剩下的异步做完,仍在同一个键和同一套状态机下面。
6.0 副作用放在闸门后面
难以撤销的操作,比如发邮件、扣款、推 ERP 单据、开工单,都要等键认领成功才执行。已经 completed 的键再来,跳过这条路径,直接返回成功。如果副作用在对端本身不幂等,就给它单独一个业务键(订单号、发票号),第二次推送也不会多出一张单据。
7.0 至少一次投递下的顺序
提供方通常不保证顺序。updated 可能比 created 先到,旧内容的重试也可能排在新内容后面。幂等解决不了这个。每个业务对象记一个版本号、序号或 updated_at,过期的写入直接丢;或者改本地状态前先从提供方拉一次当前资源。
8.0 日志和告警记什么
- 去重表按键建索引,“
evt_…处理过没有”一条查询就能回答。 - 每次尝试都记日志:键、结果(重复 / 处理中 / 已完成 / 失败)、耗时、第几次。
- 支付数据和个人信息不进共享日志,我们只记摘要和内部 ID。
- 两类情况要告警:键在 processing 里卡过了租约期;重复量突然飙升(常见于对方故障恢复后的一波重试)。
如果你在做支付、ERP 或设备云的 webhook 接收端,见 Web、云端与设备管理,也可以直接聊聊项目。
参考资料
- Stripe,Receive Stripe events in your webhook endpoint:https://docs.stripe.com/webhooks
- Stripe,Idempotent requests:https://docs.stripe.com/api/idempotent_requests
- GitHub,Best practices for using webhooks:https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
- GitHub,Redelivering webhooks:https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks
- IETF HTTPAPI 工作组,The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-07(已过期的互联网草案):https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
常见问题
对方文档说每个事件只推一次,我们还要做去重表吗?
常见的约定其实是至少一次投递:超时、5xx、网络抖动都会触发重试。同一份内容再来一次时,靠稳定的键加上覆盖对方最长重试时长的保留期,才不会把副作用做两遍。
第一次还在处理,重复的请求又到了,该返回什么?
按发送方文档的约定,返回冲突或者让它稍后再来,但不要为同一个键再起一条副作用路径。我们的做法是把这一行标成处理中并带一个租约(持有者和过期时间),落库和副作用都完成后才标完成。
处理过的键要留多久?
至少和发送方的自动重试窗口一样长,最好覆盖它公布的手动重推期。键过期后同一个事件再到,接收端会当成新事件,非幂等的操作可能又执行一次。
已经回了 200,邮件或 ERP 推送却没执行,怎么补救?
顺序要反过来:先把事件和处理状态持久化,再回 2xx,然后由这条持久记录或 outbox 去驱动副作用。写入还没落盘就回成功,之后本地一出错就没有可以恢复的记录,而发送方已经认为投递完成了。
事件有时乱序到达,幂等键能解决吗?
幂等键只管同一个事件别被应用两次。顺序要另外处理:用序号或 updated_at 丢掉过期版本,或者改本地状态前先调对方 API 取当前对象。