用途
Webhook Integration Patterns 是一项用于指导设计与实现健壮 Webhook 系统的技能，既适用于作为提供方（发送 Webhook），也适用于作为消费方（接收 Webhook）。其核心目标是在事件驱动的集成中提供可靠的交付保证、安全校验与幂等处理。
主要能力
该技能围绕以下能力展开：
- 交付保证：涉及至少一次（at-least-once）与恰好一次（exactly-once）语义。
- 安全：签名验证、密钥轮换。
- 可靠性：重试策略、死信处理（dead letter handling）。
- 可扩展性：基于队列的处理、限流。
Webhook 基本面
技能中解释了 Webhook 解决的问题：以基于推送的通知替代低效的轮询。文中给出轮询与 Webhook 的对比示意图，说明客户端无需反复询问“有没有新消息”，而是由服务端在事件发生时主动 POST 到回调地址。
Webhook 的请求结构示例包含以下关键头部：
X-Webhook-Signature：用于真实性校验的加密签名。X-Webhook-ID：用于去重的唯一事件标识。X-Webhook-Timestamp：事件发生时间。
请求体示例包含 id、type、created_at 与 data 等字段。
提供方设计
作为 Webhook 提供方，技能给出以下模式：
- 事件 Schema 设计：定义标准 Webhook 事件结构，包含生成 ID、事件类型、创建时间、API 版本、数据与幂等键，并说明事件类型遵循“资源.动作”命名（如
payment.created、payment.completed、subscription.cancelled等）。 - 签名生成：使用 HMAC-SHA256 对包含时间戳的负载签名，以防范重放攻击；并生成
Content-Type、X-Webhook-Signature、X-Webhook-Timestamp、X-Webhook-ID等头部。 - 投递系统：定义重试时间表（10 秒、1 分钟、5 分钟、30 分钟、1 小时、6 小时、24 小时），对非成功状态或异常安排重试，超过重试次数后移入死信；成功状态码包括 200、201、202、204。
- 端点管理：维护订阅端点配置，包括 URL、订阅事件、密钥、状态、连续失败计数、最后成功/失败时间；支持通配订阅
*；连续失败达到 10 次时自动禁用端点，成功后可重新激活。
消费方设计
作为 Webhook 消费方，技能给出以下模式：
- 签名验证：校验时间戳新鲜度（容忍 5 分钟），计算期望签名并使用恒定时间比较防止时序攻击；示例展示在 Flask 端点中返回 401 处理无效签名。
- 幂等处理：在处理前检查事件 ID 是否已处理，使用锁避免并发处理，处理完成后记录已处理标记（保留 7 天），并路由到对应事件类型的处理器。
- 基于队列的处理：先做结构校验，将事件入队并携带去重 ID，立即返回接收确认，由工作进程异步处理，失败时重新入队。
安全模式
- 密钥轮换：支持滚动更新密钥，在 24 小时宽限期内仍可使用旧密钥验证。
- IP 允许列表：示例列出 Stripe、GitHub、Twilio 的 IP 范围，并说明如何校验请求来源 IP。
错误处理
技能给出响应码与提供方动作的对照：
- 200-204：成功，标记已投递。
- 400：错误请求，不重试（属于自身问题）。
- 401/403：认证失败，禁用端点。
- 404：未找到，禁用端点。
- 429：被限流，带退避重试。
- 500+：服务器错误，重试。
- 超时：无响应，重试。
同时给出死信队列模式：存储失败 Webhook，支持手动重试与清理旧条目。
最佳实践
技能分别列出提供方与消费方的最佳实践：
提供方应包含事件 ID 供消费方去重、至少使用 HMAC-SHA256 签名、包含时间戳防重放、使用指数退避重试（至少 5 次）、在仪表盘提供 Webhook 日志、支持按类型过滤事件、为向后兼容对负载进行版本管理。
消费方应在处理前验证签名、快速响应（小于 5 秒）、通过队列异步处理、使用事件 ID 实现幂等、记录日志便于调试、主动监控失败。
参考资料
技能附带参考文献：references/webhook-security.md（安全实现细节）、references/provider-examples.md（Stripe、GitHub、Twilio 模式）、references/testing-webhooks.md（本地开发与测试）。
限制
资料未提供该技能的具体安装方式、运行环境、收费模式或价格信息。上述内容均来自技能说明本身，未包含官方来源之外的额外事实。