用途：这是一份面向 Webhook 接收端/处理器的通用指南，适用于任何接收 Webhook 的服务，与具体发送方平台无关。核心原则是把每个请求都当作不可信输入，直到签名验证通过为止。
主要能力与要点：
- 每个请求都要验签，未验证的 Webhook 等同于匿名互联网 POST，任何人都能伪造事件。
- 必须基于原始请求体验签，签名针对发送的确切字节计算；任何先解析 JSON 再重新序列化的框架都会破坏验证。
- 在数秒内返回 2xx，其他状态码（包括 3xx 重定向）通常被视为失败并重试，重活应异步处理。
- 处理流程：读取原始 body（验签前不解析 JSON）→ 用官方库或文档方案验签，失败返回 400 → 立即返回 2xx（如 204）→ 在后台任务/队列中按事件类型分支处理。
签名头与密钥：常见概念包括消息 ID（webhook-id）、时间戳（webhook-timestamp，用于防重放）、签名（webhook-signature，常带版本）。应使用签名密钥而非 API key，密钥需保存在服务端，不得放入客户端包或提交到仓库。
重试与自动禁用：只有 2xx 表示成功，其他状态码通常按指数退避重试；需在提供方超时（常见几秒到约 15 秒）内响应；4xx 用于拒绝伪造/错误请求，5xx/超时仅用于希望重试的瞬时故障。端点持续失败常会被自动禁用，应保持处理器健康并接入失败通知。
手动验证（仅在无官方库时）：剥离 whsec_ 前缀并 base64 解码得到 HMAC 密钥；取 webhook-id、webhook-timestamp、webhook-signature；检查时间戳容差（Standard Webhooks 为 5 分钟窗口）；以 {id}.{timestamp}.{body} 构造签名内容；用解码后的密钥计算 HMAC-SHA256 并 base64 编码；对空格分隔的 v1,<sig> 列表做常量时间比较。
常见陷阱：验签前解析 body、密钥错误或格式不对、用 curl 重放旧载荷、反向代理剥离签名头、服务器时钟不同步。
限制：头名称、密钥格式与容差因提供方而异，编写代码前须以提供方文档为准；若提供方支持 Standard Webhooks，优先使用官方 standardwebhooks 库；若通过 Svix 发送（出现 svix-id、svix-timestamp、svix-signature 头），应使用官方 Svix SDK。