处理Stripe Webhook时持续触发StripeSignatureVerificationError求助

架构老林

2026-8-16

Stripe Webhook 签名验证错误（StripeSignatureVerificationError）排查方案

以下是针对该错误的核心排查方向及解决方法：

确认签名密钥准确性
必须使用Stripe Dashboard对应Webhook端点的签名密钥（格式为whsec_xxx），而非API密钥。复制时确保无空格、字符遗漏或多余符号。

保证请求体未被修改
签名验证依赖原始请求体，若Express中间件（如express.json()）提前解析或修改了请求体，会直接导致验证失败。正确处理方式：

// 先以原始格式接收请求体，再处理
app.use('/webhook', express.raw({type: 'application/json'}));
app.post('/webhook', (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  // 后续事件处理逻辑
});

检查请求头传递完整性
确认stripe-signature请求头未被代理、服务器（如Nginx）过滤或修改。需配置相关服务保证该头信息原样传递至Express服务。
校准服务器时间
Stripe签名包含时间戳，若服务器与Stripe服务器时间偏差超过5分钟会触发错误。同步服务器时间至NTP服务器即可解决；临时排查可放宽时间容忍度（不推荐长期使用）：
```
event = stripe.webhooks.constructEvent(
  req.body,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET,
  300 // 放宽至5分钟，单位为秒
);
```
本地测试规范
使用Stripe CLI测试时，确保CLI绑定了正确的签名密钥；通过ngrok等工具暴露本地服务时，禁用压缩功能，避免请求体被篡改。