Webhook 签名验证失败

一句话：接收Webhook时，用来确认请求确实来自可信发送方的签名校验没通过，可能是密钥配置错误或请求被篡改。

它是什么

为了防止别人伪造请求冒充触发你的Webhook接收逻辑，正规的Webhook机制会在请求里带上一个签名（用密钥加密计算出的校验值），你的接收端要用同样的密钥重新计算并比对，一致才说明请求真实可信。签名验证失败说明这个比对没通过。

适合干什么

• 接入第三方Webhook（如支付回调）后签名验证报错时排查

不适合干什么

• 完全没有做签名验证机制的简单场景（那种情况下也不该有"签名验证失败"这类报错，但也意味着更容易被伪造攻击）

普通人怎么用

最常见原因是密钥配置错了（比如复制粘贴时多了空格，或者用错了环境的密钥），仔细核对你的接收端配置的密钥和发送方后台显示的密钥是否完全一致。

进阶用户怎么用

确认签名计算方式（用的哪种哈希算法、签名的是原始请求体还是处理后的数据）和文档要求完全一致，有些框架会在你读取请求体后修改了它的格式，导致签名计算时用的数据和发送方计算时不一致。

常见误区

• 以为签名验证失败就是网络问题或者对方服务出错了，实际99%是自己这边的密钥配置或者签名计算方式有偏差
• 在中间件里提前解析处理了请求体，导致做签名验证时用的不是原始的请求数据，计算出的签名自然对不上

和相似工具的区别

• 和普通的API身份验证不同：Webhook签名验证的是"这条消息内容确实来自对方且没被篡改"，而不是"你有没有权限访问"，是防篡改机制

入门步骤

• 核对密钥配置是否完全一致（注意空格、大小写）
• 确认签名计算方式和官方文档的要求一致
• 确保验证签名时用的是原始未处理的请求体数据