Webhook技能使用说明

接收：签名验证

• 务必验证HMAC签名——载荷可能被伪造；没有签名则不可信
• 常见模式：HMAC-SHA256(密钥, 原始主体)与头部值对比
• 使用原始主体字节——解析后的JSON可能重排键顺序，导致签名失效
• 时序安全比较——防止签名检查遭受时序攻击
• 对缺失或无效签名返回401拒绝——记录日志以供调查

接收：重放攻击防护

• 检查载荷或头部中的时间戳——若过于久远（>5分钟）则拒绝
• 与签名结合使用——未签名的单独时间戳可能被伪造
• 存储已处理的事件ID——即使时间窗口内也拒绝重复事件
• 时钟偏差容限：允许1-2分钟误差——但非数小时

接收：幂等性（关键）

• Webhook可能多次到达——发送方在超时、网络问题时重试
• 使用事件ID进行去重——将已处理ID存储在数据库/Redis中
• 确保处理器幂等——同一事件重复处理应产生相同效果
• 幂等性窗口：ID保留24-72小时——平衡存储与保护

接收端：快速响应

• 立即返回200/202——在队列中异步处理
• 发送方超时（通常5-30秒）——处理慢=重试=重复请求
• 返回200前进行最小验证——签名检查，然后入队
• 实际处理通过后台任务执行——失败不影响接收确认

接收端：错误处理

• 2xx = 成功，发送方不会重试
• 4xx = 永久性失败，发送方可能停止重试——用于签名错误、未知事件类型
• 5xx = 临时性失败，发送方将重试——用于下游问题
• 错误时记录完整载荷——便于调试；敏感字段需脱敏

发送端：重试策略

• 指数退避：1分钟、5分钟、30分钟、2小时、8小时——之后放弃或告警
• 限制重试次数（5-10次）——避免无限重试
• 记录投递尝试——向用户展示状态
• 4xx与5xx采用不同重试策略——4xx通常意味着停止重试

发送端：签名生成

• 在签名中包含时间戳——防止捕获的Webhook被重放
• 对原始JSON正文进行签名——记录确切的签名算法
• 头部格式：t=时间戳,v1=签名——允许版本化签名
• 提供验证代码示例——减少集成摩擦

发送：超时设置

• 5-10秒超时——不要无限等待缓慢的接收方
• 将超时视为失败——稍后重试
• 不要跟随重定向——或限制在1-2次；防止重定向循环
• 验证HTTPS证书——不要跳过验证

事件设计

• 包含事件类型：{"type": "order.created", ...}——接收方按类型过滤
• 包含时间戳：带时区的ISO 8601格式——用于排序和时效性判断
• 包含完整资源或ID——优先提供完整数据；节省接收方一次查询
• 事件版本控制：api_version字段——允许破坏性变更

交付跟踪

• 记录每次尝试：URL、状态码、响应时间、响应体
• 重试队列仪表板——让用户查看待处理/失败的交付
• 手动重试按钮——用于接收方修复后卡住的Webhook
• Webhook日志保留：7-30天——平衡调试与存储

安全清单

• 仅HTTPS——切勿将Webhook发送至HTTP端点
• 定期轮换密钥——在轮换期间支持多个活动密钥
• IP白名单可选——如提供此功能，请记录您的IP范围
• 不要在负载中包含密钥——Webhook URL本身应足够保密
• 按端点限速——一个缓慢的接收方不应影响其他接收方

常见错误

• 无签名验证——任何人都可以向您的端点发送伪造事件
• 响应前处理——超时导致重试和重复处理
• 无幂等性处理——导致重复扣款、重复记录
• 盲目信任事件数据——关键操作务必通过源API验证