| name | metaframe-webhook-pattern |
|---|---|
| category | api |
| description | Webhook模式 | API & Integration |
英文名: Webhook Pattern
分类: API 设计与集成
作者: Jeff Lindsay, 2007 (coined the term); pattern predates the name in early HTTP callback systems
复杂度: intermediate
成熟度: established
AI 相关: ✅ 是
通过HTTP回调实现事件驱动的API集成，提供实时通知
- 推送式投递：服务器在事件发生时主动向消费者注册的URL发送HTTP POST请求，逆转了传统的拉取模型
- 负载签名：请求头中的HMAC签名（使用共享密钥）允许消费者验证webhook负载来自合法发送者
- 幂等性：消费者必须使用事件ID优雅处理重复投递，因为重试逻辑可能多次投递同一事件
- 带退避的重试：对失败投递使用指数退避重试，以处理消费者的瞬时故障而不压垮恢复中的端点
- 订阅管理：自助服务API，用于注册、更新和停用webhook订阅，支持事件类型过滤
- 定义系统将发出的webhook事件，记录每种事件类型的负载模式和触发条件
- 构建订阅管理API，允许消费者注册回调URL、选择事件类型并配置用于验证的密钥令牌
- 实现事件分发系统，序列化事件、使用HMAC签名负载，并向注册的回调URL发送HTTP POST请求
- 为失败的投递添加指数退避的重试逻辑，并为持续失败的端点实现死信队列
- 为消费者提供webhook投递日志和重放功能，以便调试遗漏事件并从故障中恢复
['当消费者需要实时事件通知而不需持续轮询API时', '当与需要对平台状态变更做出反应的第三方系统集成时', '当构建自动化工作流，下游动作应在事件发生时立即触发时', '当通过向感兴趣的消费者推送更新来减少API负载，而非服务重复的轮询请求时']
- 使用HMAC为每个webhook负载签名并文档化验证过程，因为未签名的webhook极易被伪造
- 在每个负载中包含唯一事件ID，因为消费者需要它来进行幂等处理和去重
- 为重试实现带抖动的指数退避，因为对恢复中端点的同步重试会导致惊群问题
- 提供投递日志和手动重放端点，因为消费者需要调试和恢复遗漏的事件
- 不要发送不签名的webhook负载，因为这使消费者暴露于伪造和注入攻击
- 不要在没有最大重试次数和死信机制的情况下无限重试，因为这会在永久不可达的端点上浪费资源
- 不要在webhook负载中包含敏感数据（密码、令牌），因为回调URL可能经过不可信的网络
- 不要假设消费者按顺序处理事件，因为网络条件和重试可能导致事件乱序投递
Sources: SDFrame (Software Design) MetaFrame: 🔌 API & Integration / API 与集成