Stripe Webhook签名验证错误解析与中间件顺序优化

Stripe Webhook签名验证失败：错误现象与根源分析

在使用Stripe进行订阅系统开发时，开发者经常会集成Webhook来实时接收Stripe的事件通知。然而，在实现Webhook签名验证时，一个常见的错误是遇到以下提示：

Webhook signature verification failed. Webhook payload must be provided as a string or a Buffer (https://nodejs.org/api/buffer.html) instance representing the _raw_ request body.Payload was provided as a parsed JavaScript object instead.
Signature verification is impossible without access to the original signed material.

这个错误明确指出，Stripe的stripe.webhooks.constructEvent方法在尝试验证签名时，需要访问原始的、未经解析的请求体（即一个字符串或Buffer实例）。然而，它接收到的却是一个已经解析过的JavaScript对象。

问题根源在于Express应用的中间件处理顺序。在典型的Express应用中，我们常常会使用app.use(express.json());这样的全局中间件来自动解析所有传入请求的JSON格式请求体。当一个Stripe Webhook请求到达服务器时，如果express.json()中间件在Stripe Webhook处理逻辑之前执行，它就会将请求的原始JSON体解析成一个JavaScript对象，并将其赋值给request.body。此时，当stripe.webhooks.constructEvent尝试使用request.body进行签名验证时，它已经无法获取到原始的请求体内容，从而导致验证失败。

解决方案：优化Express中间件顺序

解决此问题的核心在于确保Stripe的constructEvent方法能够访问到原始的请求体。有两种主要的方法可以实现这一点：

方法一：调整全局中间件的顺序

最直接的解决方案是将Stripe Webhook的处理路由放置在任何可能解析原始请求体的全局中间件（如express.json()）之前。这样，当Webhook请求到达时，它会首先被特定的Webhook路由捕获，并在该路由内部使用express.raw()中间件来确保请求体以原始的Buffer形式存在，供Stripe进行签名验证。

示例代码：

百度文心百中

百度大模型语义搜索体验中心

22

查看详情

const express = require('express');
const stripe = require('stripe')('YOUR_STRIPE_SECRET_KEY'); // 替换为你的Stripe密钥
const app = express();

// 1. Stripe Webhook路由必须放置在 express.json() 之前
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }), // 确保请求体以原始Buffer形式存在
  (request, response) => {
    let event;
    const endpointSecret = 'whsec_YOUR_WEBHOOK_SECRET'; // 替换为你的Webhook密钥

    // 获取Stripe签名头
    const signature = request.headers['stripe-signature'];

    try {
      // 使用原始请求体进行签名验证
      event = stripe.webhooks.constructEvent(
        request.body, // 此时 request.body 是一个 Buffer
        signature,
        endpointSecret
      );
    } catch (err) {
      console.log(`⚠️  Webhook signature verification failed.`, err.message);
      return response.sendStatus(400); // 签名验证失败，返回400
    }

    // 根据事件类型处理Stripe事件
    let subscription;
    let status;

    switch (event.type) {
      case 'customer.subscription.created':
        subscription = event.data.object;
        status = subscription.status;
        console.log(`Subscription status is ${status}.`);
        // 这里可以添加你的业务逻辑，例如更新数据库
        break;
      // 可以添加更多事件类型处理
      default:
        console.log(`Unhandled event type ${event.type}.`);
    }

    // 成功处理后，返回200 OK
    response.send();
  }
);

// 2. 其他需要JSON解析的路由，可以继续使用 express.json()
// 但它必须在 webhook 路由之后
app.use(express.json());
app.use(express.urlencoded({ extended: true })); // 如果需要处理URL编码的请求体

// 其他应用路由...
app.get('/', (req, res) => {
  res.send('Hello from Express App!');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

在上述代码中，app.post('/webhook', ...) 路由被定义在 app.use(express.json()); 之前。同时，该Webhook路由内部使用了 express.raw({ type: 'application/json' }) 中间件，这确保了只有当请求路径匹配 /webhook 并且 Content-Type 为 application/json 时，请求体才会被解析为原始Buffer，而不会被express.json()提前解析。

方法二：针对性地使用 express.raw() 中间件

即使app.use(express.json())在Webhook路由之前，也可以通过在Webhook路由中明确指定express.raw()中间件来覆盖或绕过全局的JSON解析。express.raw()会确保request.body包含原始的请求体Buffer，即使全局express.json()尝试解析过，express.raw()也会在当前路由链中提供原始数据。

然而，更推荐的方法是确保express.raw()作为该特定路由的第一个体解析中间件，以避免任何潜在的冲突或不必要的解析。方法一（调整顺序）是更清晰和常见的做法。

注意事项

• express.raw() 的 type 选项： express.raw({ type: 'application/json' }) 中的 type 选项非常重要。它告诉Express只对 Content-Type 为 application/json 的请求体进行原始Buffer解析。Stripe Webhook通常会发送 application/json 类型的请求。
• Webhook Secret 安全性： endpointSecret 是用于验证Stripe Webhook签名的关键。它应该被视为敏感信息，通常从环境变量中加载，而不是硬编码在代码中。
• 错误处理： 确保对签名验证失败的情况进行适当的错误处理，例如返回HTTP 400状态码，并记录详细的错误信息，以便调试。
• 幂等性： Webhook事件可能会重复发送，因此在处理Stripe事件时，务必考虑实现幂等性，避免重复处理相同的事件。

总结

Stripe Webhook签名验证中的"Payload must be provided as a string or a Buffer"错误是由于Express中间件处理顺序不当导致的。核心解决方案是确保在stripe.webhooks.constructEvent被调用之前，request.body仍然包含原始的请求体Buffer。这通常通过将Stripe Webhook路由放置在全局express.json()中间件之前，并为该路由专门使用express.raw()中间件来实现。遵循这些最佳实践，可以有效避免签名验证失败，确保Stripe Webhook的集成既安全又稳定。

以上就是Stripe Webhook签名验证错误解析与中间件顺序优化的详细内容，更多请关注php中文网其它相关文章！