NodeJS中如何对比Dropbox Webhook请求体的HMAC SHA256签名？

我来帮你一步步搞定Dropbox Webhook的签名验证，确保收到的通知确实来自Dropbox，避免伪造请求。

核心原理回顾 #

每个通知请求包含名为X-Dropbox-Signature的请求头，该头包含以应用密钥为签名密钥对请求体生成的HMAC-SHA256签名，用于验证通知来自Dropbox。

简单说：你需要用自己的Dropbox应用密钥，对收到的原始未解析请求体生成HMAC-SHA256签名（Base64格式），然后和请求头里的X-Dropbox-Signature做安全对比。

关键注意事项 #

• 必须用原始请求体buffer：如果你的框架（比如Express）自动解析了JSON请求体，一定要先拿到原始字节流，否则签名会不匹配
• 用安全的比较方法：别直接用===对比，要用Node.js内置的时序安全方法，防止黑客利用时序攻击破解
• 应用密钥要保密：存在环境变量里，绝对别硬编码到代码中

代码实现示例 #

情况1：使用Express框架

Express默认会解析请求体，所以得先配置express.raw()中间件获取原始buffer，之后再按需解析成JSON处理业务逻辑。

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

// 从环境变量拿Dropbox应用密钥，安全第一！
const DROPBOX_APP_SECRET = process.env.DROPBOX_APP_SECRET;

// 给webhook路由配置raw中间件，获取原始请求体
app.use('/webhook', express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  // 1. 取出请求头里的签名
  const dropboxSignature = req.headers['x-dropbox-signature'];
  if (!dropboxSignature) {
    return res.status(403).send('Missing signature header');
  }

  // 2. 获取原始请求体buffer
  const requestBody = req.body;

  // 3. 本地生成HMAC-SHA256签名（转成Base64格式和Dropbox的签名一致）
  const hmac = crypto.createHmac('sha256', DROPBOX_APP_SECRET);
  hmac.update(requestBody);
  const localSignature = hmac.digest('base64');

  // 4. 安全对比两个签名（防止时序攻击）
  const signaturesMatch = crypto.timingSafeEqual(
    Buffer.from(dropboxSignature),
    Buffer.from(localSignature)
  );

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

  // 签名验证通过，接下来处理你的业务逻辑
  // 比如解析请求体：const payload = JSON.parse(requestBody.toString());

  res.sendStatus(200);
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

情况2：使用Node.js原生HTTP模块

如果不用框架，直接用原生HTTP服务，代码如下：

const http = require('http');
const crypto = require('crypto');

const DROPBOX_APP_SECRET = process.env.DROPBOX_APP_SECRET;

const server = http.createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhook') {
    res.statusCode = 404;
    res.end('Not found');
    return;
  }

  // 收集原始请求体的所有字节块
  const bodyChunks = [];
  req.on('data', (chunk) => bodyChunks.push(chunk));
  req.on('end', () => {
    const requestBody = Buffer.concat(bodyChunks);
    const dropboxSignature = req.headers['x-dropbox-signature'];

    if (!dropboxSignature) {
      res.statusCode = 403;
      res.end('Missing signature header');
      return;
    }

    // 生成本地签名
    const hmac = crypto.createHmac('sha256', DROPBOX_APP_SECRET);
    hmac.update(requestBody);
    const localSignature = hmac.digest('base64');

    // 安全对比签名
    const signaturesMatch = crypto.timingSafeEqual(
      Buffer.from(dropboxSignature),
      Buffer.from(localSignature)
    );

    if (!signaturesMatch) {
      res.statusCode = 403;
      res.end('Invalid signature');
      return;
    }

    // 验证通过，处理业务逻辑
    res.statusCode = 200;
    res.end('OK');
  });
});

server.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

常见问题排查 #

• 签名不匹配？检查是否用了原始请求体——比如Express中如果先加了express.json()，会覆盖原始buffer，一定要把express.raw()放在前面
• 应用密钥是否正确？确认是Dropbox应用的App Secret，不是App Key
• 编码问题？别随意把请求体转成字符串再转回buffer，会改变原始字节内容导致签名错误

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