按真实调试路径组织的 Stripe Webhook 指南
在本地测 Stripe、修签名错误，或在改代码后重放已保存的投递时，从这里开始。
为什么 Stripe Webhook 调试需要结构化步骤
Stripe 依赖 Webhook 通知扣款、订阅、争议等大量支付事件。当某次投递静默失败——或在预发能通过签名、线上却挂掉——结果往往是收入损失与用户困惑。问题很少出在「Webhook 本身」，而多在 Stripe 发出的载荷与你方处理器接收方式之间的断层：raw body 被改写、签名密钥用错、框架中间件过早解析 JSON 等占了失败的大头。本系列把 Stripe 调试拆成三步：本地测试、签名排障、重放——让你能定位是哪一层坏了，而不是靠猜。
如何在本地测试 Stripe Webhook
多数团队的起点：接住真实 Stripe 投递、检查原始 payload、转发到 localhost，并在改代码后重放同一条请求。
打开指南 -> 排障Stripe Webhook 签名验证失败
按最常见原因排查签名失败：密钥错误、raw body 被改写、以及过早解析 JSON 的中间件。
打开指南 -> How-to如何在本地开发中重放 Stripe Webhook 事件
当事件已经捕获，需要再一次干净验证却不想重新触发结账、账单或订阅流程时使用重放。
打开指南 ->建议阅读顺序
- 如何在本地测试 Stripe Webhook — 先搭好后续每篇都默认你已有的「捕获 → 检查 → 转发」闭环。
-
Stripe Webhook 签名验证失败
— 当事件已到但
stripe.webhooks.constructEvent()抛错时打开。 - 如何在本地开发中重放 Stripe Webhook 事件 — 闭环稳定后，用重放加快迭代而无需反复触发 Stripe。
相关产品页
- Webhook 调试器 — 实时捕获并检查 Stripe 投递
- 本地转发 — 将已捕获流量路由到本地处理器
- Webhook 重放 — 在不重新触发 Stripe 的情况下再次投递已保存事件
其他 Webhook 指南
相关文档
- HookNexus Stripe 集成文档 — 端点配置、事件筛选与签名密钥
- 转发指南 — localhost 转发在底层的运作方式
- 重放指南 — 重放配置与重试行为说明
常见问题
这些指南建议按什么顺序读？
先从本地测试建立「捕获 → 检查 → 转发」闭环；若遇到签名错误，再打开排障篇。闭环稳定后，用重放在不重复触发 Stripe 的前提下加快迭代。
用了 HookNexus 还必须装 Stripe CLI 吗？
不一定。Stripe CLI 适合触发测试事件；HookNexus 负责捕获、检查、转发与重放。很多团队两者一起用：CLI 触发，HookNexus 调试。
应该先测哪些 Stripe 事件？
通常从 checkout.session.completed 或 invoice.paid 开始——这两类最容易在业务处理里埋坑。跑通后再扩展到 customer.subscription.updated、payment_intent.succeeded 等。
能用这些指南调试 Stripe Connect Webhook 吗？
可以。Connect 的「捕获 → 检查 → 转发」流程相同；主要区别是 Connect 事件走独立端点且签名密钥不同，务必核对当前用的是哪把 secret。