Webhook

核心用法

本技能专注于 webhook 的安全实现，分为接收端与发送端两大场景。

接收端最佳实践

• 签名验证：必须使用 HMAC-SHA256 验证请求真实性，使用原始 body 字节避免 JSON 重排序导致验签失败，采用恒定时间比较防止时序攻击
• 防重放攻击：验证时间戳（拒绝 >5 分钟旧请求），结合签名确保不可伪造
• 幂等性处理：通过 event ID 去重存储（建议保留 24-72 小时），处理逻辑本身也需幂等
• 快速响应：先返回 200/202，再异步处理，避免发送方超时重试
• 错误码规范：2xx 成功、4xx 永久失败、5xx 临时失败触发重试

发送端最佳实践

• 签名生成：时间戳 + 版本化签名头（如 t=xxx,v1=sig），提供多语言验签示例
• 重试策略：指数退避（1min→5min→30min→2h→8h），区分 4xx/5xx 响应
• 超时控制：5-10 秒超时，禁止无限重定向，强制 HTTPS 证书验证

事件设计规范

包含事件类型、ISO 8601 时间戳、完整资源数据或 ID、API 版本号，便于接收方过滤与演进。

显著优点

• 覆盖完整生命周期：从设计、开发到运维监控的全链路指导
• 安全优先：将签名验证、防重放、幂等性作为强制要求而非可选
• 工程可落地：提供具体参数（超时秒数、退避间隔、保留天数）和代码模式
• 双向视角：同时指导发送方与接收方，减少对接摩擦

潜在局限性

• 未涉及特定云服务商（AWS SNS、Stripe、GitHub）的专有实现差异
• 缺少大规模高并发场景下的队列选型建议（Kafka vs RabbitMQ vs 云队列）
• 对 WebSocket/SSE 等替代方案无对比分析

适合人群

• 构建 SaaS 平台需对外提供 webhook 集成的后端工程师
• 对接第三方服务需实现接收端的安全开发者
• 负责 webhook 系统架构审查的技术负责人

常规风险

• 密钥泄露：共享 secret 需轮换机制，避免硬编码
• 时钟不同步：NTP 配置不当导致合法请求被拒或重放攻击穿透
• 存储爆炸：event ID 去重表无限增长需设置 TTL
• 下游故障：异步队列堆积需监控与告警

核心用法

本 Skill 是一份纯文档型 webhook 安全最佳实践指南，分为接收方 (Receiving) 与发送方 (Sending) 两大模块：

接收方安全要点

• 签名验证：必须使用 HMAC-SHA256 对原始请求体进行签名比对，采用防时序攻击的字符串比较，缺失或无效签名立即返回 401
• 重放防护：校验时间戳（拒绝超过 5 分钟的事件），结合签名防伪造，允许 1-2 分钟时钟偏移容差
• 幂等性处理：webhook 必然重试，需基于 event ID 去重（Redis/数据库保留 24-72 小时），确保同一事件多次处理结果一致
• 快速响应：先返回 200/202，再异步入队处理，避免发送方超时导致重复推送
• 错误码语义：2xx 成功、4xx 永久失败（停止重试）、5xx 临时失败（继续重试）

发送方安全要点

• 指数退避重试：1min→5min→30min→2h→8h，限制 5-10 次，区分 4xx/5xx 响应策略
• 签名生成：时间戳 + HMAC 签名（如 t=timestamp,v1=signature），提供多语言验证示例
• 超时与连接安全：5-10 秒超时，禁止无限重定向，强制 TLS 证书验证

事件设计与可观测性

• 事件需包含类型、ISO 8601 时间戳、完整资源或 ID；支持版本字段 api_version 管理变更
• 日志记录每次投递详情（URL、状态码、耗时、响应体），提供重试队列仪表板与手动重试功能

显著优点

1. 零代码安全风险：纯 Markdown 文档，无可执行代码、无外部依赖、无网络请求，安全审计六维满分
2. 覆盖完整生命周期：从接收、验证、处理到发送、重试、监控，形成闭环安全指导
3. 实操性强：提供具体算法（HMAC-SHA256）、时间参数（5 分钟窗口、指数退避间隔）、HTTP 状态码语义等可量化标准
4. 防御深度足：同时覆盖传输层（HTTPS/TLS）、应用层（签名/重放/幂等）、运维层（日志/告警/手动重试）

潜在局限

• 无框架特定代码：仅提供通用模式，Node.js、Python、Go 等语言需自行实现
• 无交互式工具：缺少签名验证器、webhook 测试端点等即用工具链接
• 事件版本策略简略：api_version 字段提及但未详述兼容性迁移方案

适合人群

• 后端工程师设计 webhook 系统架构
• 安全审计人员制定 webhook 安全基线
• 技术负责人评审第三方 webhook 集成方案

常规风险

• 实现偏差风险：开发者可能误用 JSON.stringify 代替 raw body 导致签名失败，或忽略时序安全比较
• 时钟同步问题：NTP 漂移可能导致合法事件被误判为重放攻击
• 幂等窗口配置不当：24-72 小时窗口过长增加存储成本，过短则无法防御延迟重试
• secret 轮转中断：未支持多 secret 并发期会导致轮转期间验证失败