Laravel使用Spatie Webhook Client报The signature is invalid错误咨询

完整报错信息如下：
The signature is invalid.

{"exception":"[object] (Spatie\\WebhookClient\\Exceptions\\WebhookFailed(code: 0): The signature is invalid. at /home//public_html//vendor/spatie/laravel-webhook-client/src/Exceptions/WebhookFailed.php:11)"}

常见触发原因 #

• 签名密钥不匹配：config/webhook-client.php中配置的signing_secret与webhook发送方后台设置的密钥不一致，是最高发的原因
• 签名头配置错误：Spatie默认读取Signature请求头获取签名，若发送方将签名放在自定义头字段（如X-Platform-Webhook-Sign），未修改配置中signature_header_name参数会导致验证失败
• 请求体被篡改：请求经过反向代理、CDN、项目全局中间件时被修改，比如自动转义特殊字符、补全空字段，导致本地重新计算的签名与发送方签名不一致
• 签名算法不匹配：发送方生成签名使用的算法（如SHA1、MD5）与Spatie默认使用的SHA256算法不一致
• 签名规则不兼容：部分发送方返回的签名带有算法前缀（如sha256=abc123xxx），默认验证器直接拿带前缀的内容和计算出的哈希对比，必然验证失败
• 多webhook配置混用：配置了多个不同平台的webhook接收规则时，路由关联了错误的签名配置组

排查步骤 #

• 逐字符核对密钥：将你本地配置的signing_secret与发送方后台配置的密钥做完全比对，排查多余空格、换行、大小写错误
• 打印原始请求日志：在webhook路由最前面添加临时日志，输出完整请求头$request->headers->all()和原始请求体$request->getContent()，确认签名头存在、请求体和发送方推送的原始内容完全一致
• 手动计算签名对比：使用本地密钥、拿到的原始请求体，严格按照发送方提供的签名生成规则手动计算哈希，和请求头中的签名做对比，若不一致优先排查签名生成逻辑是否匹配
• 检查中间件逻辑：排查项目全局中间件，确认是否有TrimStrings、ConvertEmptyStringsToNull等会修改请求内容的中间件作用于webhook路由

修复方案 #

• 修正基础配置：如果是密钥、签名头名称、算法不匹配，直接修改config/webhook-client.php对应参数即可，修改后执行php artisan config:clear清除配置缓存
• 自定义签名验证器：如果发送方签名规则和Spatie默认规则不一致，自定义实现Spatie\WebhookClient\SignatureValidator\SignatureValidator接口，重写isValid方法实现适配逻辑，再将配置中signature_validator替换为自定义类即可
• 排除请求修改中间件：在app/Http/Kernel.php中将webhook路由路径添加到修改请求类中间件的$except数组，避免请求体被篡改
• 隔离多webhook配置：每个不同平台的webhook单独配置一组签名参数，路由中指定对应配置名，避免配置混用

内容的提问来源于stack exchange，提问作者user13091150