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进行签名验证。
示例代码：
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的集成既安全又稳定。
