关于 webhook-handler-patterns
webhook-handler-patterns 是一项面向构建 Webhook 接收端的开发技能，提供从验签、解析到幂等处理的顺序指南，并涵盖错误、重试及框架注意事项。
主要功能
- 01按顺序验签、解析和处理事件
- 02幂等处理以避免重复执行
- 03错误响应、日志与死信队列建议
- 04重试调度与退避模式
- 05Express.js、Next.js 和 FastAPI 指南
适用场景
- 01实现安全的 Webhook 接收端
- 02避免重复 Webhook 事件造成重复操作
- 03配置失败响应与重试行为
- 04处理框架中的原始请求体和中间件顺序
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/webhook-handler-patterns确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/error-handling.mdhandler-sequence.mdidempotency.mdretry-logic.mdreferences/frameworks/express.mdfastapi.mdnextjs.md详细介绍
Webhook 处理程序模式
何时使用此技能
- 遵循正确的 webhook 处理程序顺序（验证 → 解析 → 幂等处理）
- 实现幂等的 webhook 处理程序
- 处理错误并配置重试行为
- 了解特定框架的注意事项（原始请求体、中间件顺序）
- 构建可用于生产环境的 webhook 基础设施
资源
处理程序顺序
- references/handler-sequence.md - 先验证，再解析，最后进行幂等处理
最佳实践
- references/idempotency.md - 防止重复处理
- references/error-handling.md - 返回代码、日志记录、死信队列
- references/retry-logic.md - 提供商的重试计划、退避模式
框架指南
- references/frameworks/express.md - Express.js 模式和注意事项
- references/frameworks/nextjs.md - Next.js App Router 模式
- references/frameworks/fastapi.md - FastAPI/Python 模式
快速参考
处理程序顺序
- 首先验证签名 — 使用原始请求体；对于无效请求，返回 4xx。
- 其次解析载荷 — 验证通过后，解析或构造事件。
- 最后进行幂等处理 — 检查事件 ID，然后处理；重复事件返回 2xx。
请参阅 references/handler-sequence.md，了解详情以及提供商验证和幂等模式的链接。
响应代码
| 代码 | 含义 | 提供商行为 |
|---|---|---|
2xx | 成功 | 不重试 |
4xx | 客户端错误 | 通常不重试（429 除外） |
5xx | 服务端错误 | 采用退避策略重试 |
429 | 请求频率受限 | 延迟后重试 |
幂等性检查清单
- 从载荷中提取唯一事件 ID
- 检查事件是否已处理
- 在事务中处理事件
- 处理成功后存储事件 ID
- 对重复事件返回成功
相关技能
- stripe-webhooks - Stripe 支付 webhook 处理
- shopify-webhooks - Shopify 电商 webhook 处理
- github-webhooks - GitHub 仓库 webhook 处理
- resend-webhooks - Resend 邮件 webhook 处理
- chargebee-webhooks - Chargebee 账单 webhook 处理
- clerk-webhooks - Clerk 身份验证 webhook 处理
- elevenlabs-webhooks - ElevenLabs webhook 处理
- openai-webhooks - OpenAI webhook 处理
- paddle-webhooks - Paddle 账单 webhook 处理
- hookdeck-event-gateway - 可替代队列的 webhook 基础设施 — 为 webhook 处理程序提供有保证的投递、自动重试、重放、速率限制和可观测性
评论
支持 Markdown