如何在本地测试 Webhooks：完整2026指南

Source: Dev.to

介绍

在本地开发时测试 webhook 可能会很棘手，因为你的 localhost 并不能被互联网访问。Stripe、GitHub 或 Shopify 等服务需要一个公开的 URL 来向你的 webhook 端点发送 HTTP POST 请求。

隧道工具

ngrok

ngrok http 3000

• 创建一个公开的 URL（例如 https://abc123.ngrok.io），该 URL 会转发到 localhost:3000。
• 免费套餐的 URL 每次重启都会变化；付费套餐（$8‑25/月）提供稳定的 URL。

Cloudflare Tunnel（原 Argo Tunnel）

cloudflared tunnel --url http://localhost:3000

• 免费且可与已有的 Cloudflare 配置集成。

localtunnel

npx localtunnel --port 3000

• 开源替代方案；可靠性可能有所不同。

捕获服务

捕获服务充当传入 webhook 的收件箱，允许你检查、存储并在以后重新播放它们。

• 永久 URL – 如 https://thunderhooks.com/h/my-project。

工作流

1. 在提供商（Stripe、GitHub 等）中配置将 webhook 发送到永久 URL。
2. webhook 被存储（通常 7‑30 天），可以通过仪表盘进行检查。
3. 准备好后，将捕获的 webhook 重新发送到本地隧道 URL。

相比直接隧道的优势

• 不需要 24/7 保持隧道在线；未收到的请求会被排队。
• 可以轻松多次重新播放相同的负载进行调试。
• 省去在提供商配置中不断更新 URL 的麻烦。

权衡

• 需要两步过程（捕获 → 重新播放），而不是直接转发，但通常值得获得的灵活性。

提供商特定的测试工具

Stripe CLI

stripe listen --forward-to localhost:3000/webhooks/stripe
stripe trigger payment_intent.succeeded

• 将实时 Stripe 事件转发到本地服务器。
• 允许你按需触发测试事件。
• 仅适用于 Stripe。

GitHub

• 没有内置转发功能，但可以使用 GitHub API 在设置页面 重新投递 webhook。

推荐工作流

开发最佳实践

• 签名验证 – 开发阶段也不要跳过；在生产环境前务必启用。参见 Stripe 的签名验证文档。
• 环境变量 – 为不同环境（本地、预发布、生产）存储 webhook URL。
• 幂等性 – webhook 可能会被多次投递；确保你的处理程序能够优雅地处理重复请求。通过重新播放相同的 webhook 进行测试。
• 超时处理 – 快速返回 2xx 状态（30 秒以内）。将繁重的处理工作转移到后台任务。

部署前检查清单

• 处理程序及时返回 2xx 状态
• 已启用签名验证
• 已处理重复投递（幂等性）
• 失败日志记录包含足够的上下文信息
• 为临时失败实现了重试逻辑
• 超时处理工作正常

资源

• ngrok Documentation
• Stripe Webhooks Guide
• Stripe CLI Documentation
• Cloudflare Tunnel Setup
• localtunnel on GitHub