Stripe Webhook丢事件、重复投递或乱序怎么办：重试、幂等与补偿排查
先在 Stripe Dashboard 的 Webhooks 投递详情中确认事件是否生成、投向哪个端点、每次响应码和下一次重试时间。接收端使用原始请求体、Stripe- 和正确的 endpoint secret 验签；验签后把 event.id 以数据库唯一约束写入收件箱，可靠入队并立即返回 2xx。业务消费者按 Stripe 对象当前状态决定动作，不依赖事件抵达顺序；涉及付款、退款、订阅等关键状态时，用事件中的对象 ID 调 Stripe API 回查。恢复故障后，从未投递事件列表补偿处理，并保留定期对账任务。
本文目录（15 节）
直接答案
先在 Stripe Dashboard 的 Webhooks 投递详情中确认事件是否生成、投向哪个端点、每次响应码和下一次重试时间。接收端使用**原始请求体**、Stripe- 和正确的 endpoint secret 验签；验签后把 event.id 以数据库唯一约束写入收件箱，可靠入队并立即返回 2xx。业务消费者按 Stripe 对象当前状态决定动作，不依赖事件抵达顺序；涉及付款、退款、订阅等关键状态时，用事件中的对象 ID 调 Stripe API 回查。恢复故障后，从未投递事件列表补偿处理，并保留定期对账任务。
一、先区分“事件没生成”和“端点没处理”
第一步不是翻应用日志，而是查看 Stripe 的事件与端点投递记录。若目标事件根本没有生成，应检查测试/正式模式、账户或 Connect 账户范围、订阅的事件类型以及触发业务是否真正完成。若事件存在但没有投向该端点，通常是端点事件选择、账户上下文或目标 URL 配置问题。
若投递记录存在，就逐次查看 HTTP 状态、响应时间和错误。2xx 表示 Stripe 认为本次投递成功；3xx 不是成功确认，4xx 多半是路由、鉴权、CSRF 或验签问题，5xx 与超时则要查应用、反向代理、数据库和队列。不要用“后台最终写入了订单”推断 Stripe 一定收到了成功响应。
二、确认模式、账户与端点完全一致
测试模式与正式模式的事件、密钥和端点配置相互独立。排查时同时记录事件 ID、livemode、account、endpoint ID 与请求 URL。Connect 平台还要区分平台账户事件和 connected account 事件；只监听平台账户的端点不会自动得到所有子账户事件。
常见误判是开发者在 Dashboard 看到测试事件，却查看正式环境日志；或部署后仍使用旧端点 secret。建立环境清单，明确每个 endpoint ID 对应的域名、模式、账户范围、订阅事件和 secret 版本，避免只凭 URL 猜测。
三、验签必须使用原始请求体
Stripe 验签依赖未经修改的请求字节、Stripe- 请求头与该端点的 signing secret。JSON 中间件若先解析、重新序列化、改变空白或编码，得到的内容就不再是原始请求体，签名会失败。框架升级后突然大量 400 时，应优先检查 body parser 和路由中间件顺序。
CLI 转发使用的 secret 与 Dashboard 已部署端点的 secret 不是同一个概念，不能混用。日志可记录 event ID、endpoint ID、签名时间戳和分类后的失败原因，但不要输出 secret、完整签名头或敏感支付信息。生产环境还应使用官方库的签名验证函数，并保留合理的时间容差来降低重放风险。
四、为什么事件会重复
如果应用已完成业务写入，却在返回 2xx 前超时或连接中断，Stripe 无法确认成功，就会再次投递。同一个业务对象也可能合法地产生多个不同事件，因此既要防止同一 event.id 重复消费，也要让业务动作自身具有幂等性。
推荐建立 webhook inbox 表，以 Stripe 账户加 event.id 建唯一索引，并记录事件类型、对象 ID、创建时间、接收时间、载荷摘要、处理状态和错误。两个实例并发收到同一事件时，由数据库唯一约束决定首次接收者；不要使用“先查再插”的竞态写法。已存在的事件直接返回 2xx，而不是返回 409 或 500 引发更多重试。
五、快速返回2xx，耗时工作异步执行
Webhook 路由只做原始体验签、最小字段检查、收件箱持久化和可靠入队。发邮件、生成发票、调用第三方系统、刷新缓存或复杂报表都应由后台消费者处理。若必须先执行所有业务再响应，任何慢查询和外部 API 波动都会扩大重试和重复副作用。
“先返回 200 再把消息放进内存队列”也不可靠：进程可能在响应后、入队前退出。应先把事件持久化到数据库或可靠消息系统，确认保存成功后再返回。后台消费者失败时更新尝试次数与最后错误，由内部重试机制接管，不要求 Stripe 重发来充当唯一恢复手段。
六、不要依赖事件到达顺序
创建订阅、生成发票和支付成功等事件可能相隔很短，但网络投递不保证按业务链顺序到达。消费者若假设 customer. 一定先于 invoice.paid，就会在乱序时访问尚未创建的本地记录。
处理策略是把事件视为“状态发生过的通知”，而不是完整状态机命令。缺少依赖对象时，先根据事件中的 customer、subscription、invoice 或 payment intent ID 调 Stripe API 获取当前对象，再以当前状态执行可重复的 upsert。状态更新要带版本、业务时间或允许的状态转换，防止旧事件覆盖新状态。
七、事件级去重还不够
不同 event ID 可能指向同一业务结果。例如多个相关事件都可能触发“给客户开通权限”。若每个消费者都无条件开通或发信，即使事件级去重正确，副作用仍可能重复。
为关键动作建立业务幂等键，例如 grant_access:subscription_id:period_start、refund_notice:refund_id。数据库用唯一约束保护动作记录，外部 API 若支持 idempotency key，也使用稳定的业务键。事务中同时写入业务状态与 outbox，再由发送器投递邮件或消息，可减少数据库提交成功但外部通知状态未知的窗口。
八、恢复未投递事件
端点恢复后，先修复根因并让实时流量稳定，再处理停机期间的未投递事件。Stripe 官方提供查询未成功投递事件的流程；补偿程序仍要走同一套收件箱、去重和消费者逻辑，不能另写一条绕过幂等检查的“快速导入”路径。
补偿时按小批次拉取，记录游标、事件 ID、对象 ID、处理结果和失败原因。若对象的当前状态已经包含该事件的结果，处理器应安全跳过或完成缺失副作用。手动补偿与 Stripe 自动重试可能同时发生，因此数据库唯一约束必须始终有效。
九、建立对象级对账兜底
Webhook 不是财务账本的唯一来源。对付款、退款、争议、订阅与转账建立周期性对账：按时间窗口从 Stripe API 拉取对象，与本地订单和动作记录比对。对账任务发现缺失时写入补偿队列，而不是直接在扫描进程里执行不可逆副作用。
时间窗口应有重叠，并使用对象 ID 去重，以覆盖延迟和分页边界。记录最后成功游标不能替代重叠扫描；若游标更新与处理结果不在同一可靠流程中，进程崩溃仍可能留下空洞。
十、按症状定位根因
如果所有请求都是 400，检查原始请求体、endpoint secret、时钟和中间件；如果 Dashboard 显示超时，检查路由耗时、数据库锁和同步外部调用；如果同一 event ID 多次产生副作用，检查唯一索引和事务边界；如果不同 event ID 重复开通权益，增加业务幂等键；如果状态回退，检查是否用到达顺序覆盖当前对象状态。
若只有部分事件缺失，核对端点订阅类型、账户范围和 API 版本，同时查询事件是否实际生成。若故障仅发生在 Connect 子账户，重点检查 Stripe-Account 上下文以及平台端点是否配置为接收 connected account 事件。
十一、上线前验收清单
在测试环境连续验证正常事件、重复投递、消费者失败重试、乱序事件、端点短暂停机与恢复补偿。确认重复 event ID 只保留一条收件记录，同一业务动作只执行一次，路由能快速返回 2xx，失败消费者可以重跑，旧事件不会覆盖新状态。
再验证测试与正式 secret 隔离、日志不泄密、Dashboard 能关联本地 trace ID、未投递事件可批量补偿、对象对账能发现人为制造的缺口。最后用小额真实流程做 canary，并为异常率、非 2xx、处理延迟、积压量和对账差异设置告警。
常见问题 FAQ
返回200以后为什么还看到重复事件？
可能是先前一次响应未被 Stripe 成功接收，也可能是业务对象产生了多个不同事件。先比较 event.id；相同 ID 用收件箱唯一约束去重，不同 ID 再用对象 ID 和业务幂等键判断副作用是否已经完成。
能不能按事件created时间排序后再处理？
排序只能帮助回放，不能解决实时依赖和旧状态覆盖。消费者仍应回查对象当前状态，使用允许的状态转换或版本判断，并保证处理可重复。
验签失败时可以先解析JSON再重建字符串吗？
不可以。重建后的空白、字段顺序或编码可能变化。必须保存框架收到的原始请求字节，并把它直接交给 Stripe 官方库验签。
手动补偿会不会和自动重试冲突？
可能同时发生，所以两条路径必须共用同一个持久化收件箱、唯一约束和业务幂等机制。补偿任务不能绕过去重层。
是否可以只依赖Webhook，不做对账？
不建议。支付和订阅属于关键业务状态，应使用对象级周期对账发现配置错误、长期失败或处理器缺陷留下的缺口。
总结
Stripe Webhook 的可靠性不是“收到一次请求”就结束，而是完整链路：Dashboard 投递证据定位、原始体验签、持久化收件箱、快速 2xx、异步幂等消费、对象当前状态回查、未投递事件补偿和周期对账。只要事件级与业务级去重都落在数据库约束上，并且不依赖到达顺序，重复、乱序和短期停机就能从事故变成可恢复的正常场景。
官方资料
- Stripe Docs：Webhooks：https:
/ / docs. stripe. com/ webhooks - Stripe Docs：Resolve webhook signature verification errors：https:
/ / docs. stripe. com/ webhooks/ signature - Stripe Docs：Process undelivered webhook events：https:
/ / docs. stripe. com/ webhooks/ process- undelivered- events - Stripe Docs：Webhook best practices：https:
/ / docs. stripe. com/ webhooks/ best- practices