实现 Webhook 处理器时如何正确验签、幂等与重试

在编写 Webhook 接收端点时，按正确顺序验签、解析并幂等处理事件，并配置合理的响应码与重试行为。

适用场景

解决思路

1. 按固定顺序处理：先验签（verify signature），再解析（parse payload），最后幂等处理（handle idempotently）。
2. 验签时使用原始请求体（raw body），对无效请求返回 4xx 拒绝。
3. 验签通过后再解析或构造事件对象。
4. 幂等处理：先提取事件 ID，检查该事件是否已处理过，再在事务中处理事件，成功后存储事件 ID，对重复事件直接返回 2xx。
5. 按响应码约定返回：2xx 表示成功（提供方不重试）；4xx 表示客户端错误（通常不重试，429 除外）；5xx 表示服务端错误（提供方按退避重试）；429 表示被限流（延迟后重试）。
6. 配置错误处理：合理返回码、记录日志、必要时使用死信队列（dead letter queue）。
7. 配置重试逻辑：遵循提供方的重试时间表，并实现退避（backoff）模式。
8. 注意框架特定陷阱：Express、Next.js（App Router）、FastAPI 各自的 raw body 获取与中间件顺序问题。
9. 参考各提供方专用技能（Stripe、Shopify、GitHub、Resend、Chargebee、Clerk、ElevenLabs、OpenAI、Paddle）处理对应 webhook。
10. 如需保证投递、自动重试、重放、限流与可观测性，可考虑使用 Hookdeck Event Gateway 等 webhook 基础设施替代自建队列。

适用边界 · 注意事项

• 尚未确定使用哪个 webhook 提供方或其签名验证机制时，需先查阅对应提供方的专用技能。
• 仅做一次性脚本或本地调试、不涉及生产投递可靠性时，无需完整实现幂等与重试逻辑。