技能介绍

要解决的痛点

Stripe 的 Webhook 回调是明文 HTTP，你的服务端口只要被看见，任何人都能伪造一个 POST /webhook 请求。不验证签名的后果很直接：伪造支付成功通知、绕过后端逻辑直接给用户发货、套取订单金额。手工验证 HMAC 可行，但 Stripe 的 Stripe-Signature 头里带了时间戳和签名片段数组，还要处理 t= 与 v= 的格式，自己拼字符串很容易踩坑——尤其是原始请求体必须逐字节保留，一旦被中间件格式化或重新序列化，签名就永远对不上。

这个技能做了什么

核心是调用 Stripe 官方 Node 库的 stripe.webhooks.constructEvent 方法，传入原始请求体和配置好的端点密钥，让 SDK 完成签名校验，而不是自己写 HMAC 循环。关键步骤：

保留原始 body：在 Express 等中间件解析 JSON 之前拦截，拿到未经修改的字节流
读取 Stripe-Signature 头：把整个头透传给 SDK，由它解析时间戳与多版本签名片段
容差窗口校验：SDK 会拒绝时间戳过于久远的请求，这正是防重放的机制——攻击者重放旧报文时，会因超出容忍范围被拒绝
失败上报 Datadog：校验失败不是静默吞掉，而是通过 Datadog Logs API 记录，方便你在监控里按错误类型聚合排查

校验通过后拿到的 event 对象即可直接使用，包含 type、data.object 等字段，后续逻辑按事件类型分发即可。

适用边界与注意点

只覆盖签名验证这一步：拿到合法 event 之后的幂等处理、业务状态机、金额复核，都还需要你自己实现
原始 body 是命门：一旦上游有任何中间件 JSON.parse 后再 JSON.stringify，签名必然失效，错误现象是所有请求都报签名不匹配
密钥管理：端点密钥要放在环境变量或配置中心，不要写进代码仓库；Stripe 支持按端点独立密钥，轮换时注意新旧密钥的兼容窗口
容差窗口不是无限宽：Stripe 默认的容忍范围有限，高延迟环境或消息堆积重放时会拒绝，这属于预期行为而非 bug
Datadog 上报需要额外配置：若未接入 Datadog Logs API，失败日志会发不出去，建议先确认该依赖可用再依赖此能力

校验逻辑集中在一处后，整个 Webhook 入口的安全姿态会明显收敛：非法请求在到达业务代码之前就被挡掉。