Express.js 中正确处理 Svix Webhook 验证的注意事项

在 Express.js 应用中集成 Svix 的 Webhook 验证功能时，开发者可能会遇到一个常见但容易忽视的问题：请求体(body)的解析顺序问题。本文将深入分析这个问题及其解决方案。

问题现象

当开发者按照 Svix 官方文档的推荐方式，使用 bodyParser.raw({ type: "application/json" }) 中间件来处理 Webhook 请求时，可能会遇到以下错误：

Error verifying the webhook: Expected payload to be of type string or Buffer.

这个错误表明 Svix 的验证方法期望接收原始字符串或 Buffer 类型的请求体，但实际上却收到了一个 JavaScript 对象。

问题根源

这个问题的根本原因在于 Express.js 中间件的执行顺序。如果应用中有 express.json() 中间件在 Webhook 路由之前注册，那么请求体会先被解析为 JavaScript 对象，而不是保持原始格式。

具体来说：

1. express.json() 会将请求体解析为 JavaScript 对象
2. 后续的 bodyParser.raw() 中间件不会重新解析已经被解析过的请求体
3. 最终传递给 Svix 验证方法的是一个对象而非原始数据

解决方案

解决这个问题的方法很简单但很重要：调整中间件的注册顺序。具体做法是：

1. 将 Webhook 路由放在其他可能解析请求体的中间件之前
2. 确保 bodyParser.raw() 是第一个处理 Webhook 请求的中间件

正确的代码结构应该是：

// 首先注册 Webhook 路由
app.post('/webhook', bodyParser.raw({ type: 'application/json' }), webhookHandler);

// 然后注册其他可能解析请求体的中间件
app.use(express.json());

最佳实践

1. 明确中间件顺序：始终考虑中间件的执行顺序对请求处理的影响
2. 隔离特殊路由：将需要特殊处理的 Webhook 路由与其他常规 API 路由分开
3. 测试验证：编写测试用例验证 Webhook 验证功能是否正常工作
4. 环境检查：确保 Webhook 密钥等敏感信息已正确配置

总结

在 Express.js 应用中正确处理 Webhook 验证需要开发者对中间件的执行顺序有清晰的理解。通过调整中间件注册顺序，可以确保 Svix 接收到正确的原始请求体格式，从而顺利完成 Webhook 验证。这个问题虽然简单，但却是许多开发者在集成第三方 Webhook 服务时容易忽视的一个关键点。