Webhook signature verification failed

一句话：Webhook签名校验失败，通常是密钥、原始请求体、环境、时间戳或中间件配置不对。

它是什么

Webhook signature verification failed 表示系统收到了第三方平台的回调，但无法确认这个请求确实来自对方。常见于Stripe、GitHub、支付平台、自动化平台。签名失败不能忽略，否则可能被伪造请求欺骗系统。

适合干什么

• 接支付回调的开发者
• 使用Stripe、GitHub Webhook、飞书回调的人
• 做自动化集成和SaaS后台的人
• 排查线上回调失败的团队

不适合干什么

• 想直接关闭签名校验上线
• 没有回调日志和密钥管理权限
• 不区分测试环境和生产环境

普通人怎么用

• 确认使用的是正确环境的Webhook secret
• 检查是否用原始请求体做签名校验
• 确认请求头里的签名字段没有丢失
• 检查本地和线上环境变量是否一致
• 查看平台后台是否发送到正确URL

进阶用户怎么用

• 为不同事件源保存不同secret
• 记录签名失败的请求头和事件ID但不要记录敏感密钥
• 检查代理、网关和body parser是否修改请求体
• 对时间戳容忍窗口做合理配置
• 区分重放攻击、密钥轮换和普通配置错误

常见误区

• 先JSON.parse再校验签名
• 测试环境secret拿去生产用
• 复制Webhook URL后忘记更新平台后台
• 为了让回调通直接跳过校验

和相似工具的区别

• 签名失败 vs 401未授权：
• 签名失败 vs Webhook 404：

入门步骤

• 确认平台和环境
• 核对secret
• 检查原始body
• 检查请求头
• 本地复现
• 修复后重放事件测试

推荐工具（第三方）

Stripe CLI、ngrok、Postman、Sentry、服务器日志