如何在Express.js中验证Kentico Cloud Webhook签名

我之前也踩过这个坑，官方文档只讲了签名机制但没给Express的具体实现，折腾了一阵才摸透，现在把完整的实现思路和代码分享给你：

先搞懂核心逻辑 #

Kentico Cloud会用你在后台配置的Webhook密钥，对原始请求体做HMAC-SHA256哈希，把结果放到请求头的X-KC-Signature里。我们要做的就是在Express里拿到一模一样的原始请求体，用同一个密钥生成哈希，再和请求头里的签名做安全比对。

具体实现步骤 #

1. 准备好你的Webhook密钥

去Kentico Cloud后台的Webhook配置页面，找到你设置的密钥，最好存到环境变量里（别直接硬编码在代码里，不安全），比如用process.env.KENTICO_WEBHOOK_SECRET来读取。

2. 配置Express路由，获取原始请求体

Express默认会自动解析JSON请求体，但我们需要原始的字节数据才能生成正确的哈希，所以要在Webhook的专属路由上用express.raw()中间件，指定类型为application/json：

3. 编写签名验证逻辑

直接上完整可运行的代码，每一步都加了注释：

const express = require('express');
const crypto = require('crypto');
const app = express();

// 从环境变量读取密钥，记得替换成你自己的
const WEBHOOK_SECRET = process.env.KENTICO_WEBHOOK_SECRET || 'your-fallback-secret';

// 专门处理Kentico Webhook的路由
app.post('/kentico-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  // 第一步：获取请求头里的签名
  const receivedSignature = req.headers['x-kc-signature'];
  
  // 没有签名直接拒绝请求
  if (!receivedSignature) {
    return res.status(403).send('Missing required signature header');
  }

  // 第二步：用原始请求体生成对比用的签名
  const generatedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body) // req.body是原始buffer，直接使用即可
    .digest('hex');

  // 第三步：安全比对签名（一定要用timingSafeEqual，防止时序攻击）
  const isSignatureValid = crypto.timingSafeEqual(
    Buffer.from(receivedSignature, 'hex'),
    Buffer.from(generatedSignature, 'hex')
  );

  if (!isSignatureValid) {
    return res.status(403).send('Invalid webhook signature');
  }

  // 签名验证通过，接下来处理你的业务逻辑
  // 把原始buffer转成JSON对象
  const webhookData = JSON.parse(req.body.toString());
  console.log('Valid webhook received:', webhookData);

  // 给Kentico返回200表示接收成功
  res.status(200).send('Webhook processed successfully');
});

// 启动服务
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}, ready for Kentico webhooks`);
});

关键注意事项 #

• 绝对不能用解析后的JSON对象生成哈希：如果用express.json()中间件，Express会把请求体转成JS对象，再序列化的话格式（比如空格、键的顺序）可能和Kentico发送的原始数据不一致，导致哈希完全不匹配。
• 用timingSafeEqual而不是===：普通的字符串比较会因为字符匹配的位置不同而耗时不同，攻击者可以通过时序分析来破解你的密钥，timingSafeEqual会以固定时间完成比较，避免这个风险。
• 密钥要完全一致：Kentico后台的密钥和你代码里的密钥必须一模一样，大小写、空格都不能错，否则签名肯定不匹配。

测试方法 #

你可以用Postman模拟请求验证：

1. 准备一段JSON作为请求体（比如Kentico官方提供的Webhook示例数据）
2. 用你的密钥对这段原始JSON字符串生成HMAC-SHA256哈希（可以用在线工具或者Node.js脚本生成）
3. 在请求头里添加X-KC-Signature，值为生成的哈希
4. 发送POST请求到你的路由，看是否返回200

这样就能确保你的验证逻辑没问题了。

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