Webhook 设计

服务端在事件发生时向订阅方回调 HTTP 请求的反向集成方式;要点是签名验证、重试策略、去重键与订阅生命周期管理,避免把可靠性问题转嫁给接收方。

签名HMAC 签名加时间戳,接收方校验防伪造重放
重试指数退避重试若干次,接收方按事件 ID 去重
订阅订阅端点验证、停用与审计

签名校验示意(伪代码)

签名校验示意(伪代码)
sign = HMAC_SHA256(secret, timestamp + '.' + body)
if now - timestamp > 300s: reject      // 防重放窗口
if not verify(sign, header.signature): reject
if eventId in processed(): return 200   // 幂等去重
回调不可靠是常态:投递语义(至少一次)要写进文档,并要求接收方实现幂等。

易错点

  • 无签名校验,接收方被伪造请求诱导处理
  • 回调无重试与告警,事件丢失后无法追溯

数据来源与参考

  • Stripe 文档:Webhooks(签名与重试)
  • GitHub 文档:Webhooks
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌