Node.js 验证 Webhook 签名:先保留原始请求体

举报
yd_235245466 发表于 2026/11/09 05:19:58 2026/11/09
【摘要】 接收 Webhook 时,业务处理之前通常需要先验证消息来源和内容是否被篡改。下面用 Node.js 内置 crypto 模块,演示一种自定义的 HMAC-SHA256 验签流程。示例只在本地计算,不启动服务、不请求外网;它不是任何具体平台的协议实现。本文主要内容由 AI 生成,并经代码测试校验。 按原始字节验签假设发送方和接收方约定共享密钥,对原始请求体计算 HMAC-SHA256,并把结...

接收 Webhook 时,业务处理之前通常需要先验证消息来源和内容是否被篡改。下面用 Node.js 内置 crypto 模块,演示一种自定义的 HMAC-SHA256 验签流程。示例只在本地计算,不启动服务、不请求外网;它不是任何具体平台的协议实现。

本文主要内容由 AI 生成,并经代码测试校验。

按原始字节验签

假设发送方和接收方约定共享密钥,对原始请求体计算 HMAC-SHA256,并把结果放在格式为 sha256=<64位十六进制> 的签名头中。保存为 hmac-demo.cjs:

'use strict';

const { createHmac, timingSafeEqual } = require('node:crypto');

function verifyHmac(key, body, header) {
  if (!Buffer.isBuffer(key) || key.length === 0 || !Buffer.isBuffer(body)) {
    return false;
  }
  if (typeof header !== 'string' || header.length !== 71 ||
      !/^sha256=[a-fA-F0-9]{64}$/.test(header)) {
    return false;
  }

  const actual = Buffer.from(header.slice('sha256='.length), 'hex');
  const expected = createHmac('sha256', key).update(body).digest();
  return timingSafeEqual(actual, expected);
}

if (require.main === module) {
  // 仅供本地演示,不能用作真实密钥。
  const key = Buffer.from('demo-key-not-for-production', 'utf8');
  const body = Buffer.from('{"event":"build.done","id":42}', 'utf8');
  const signature = 'sha256=' + createHmac('sha256', key).update(body).digest('hex');
  const changed = Buffer.from('{"event":"build.done","id":43}', 'utf8');

  console.log('original:', verifyHmac(key, body, signature));
  console.log('tampered:', verifyHmac(key, changed, signature));
  console.log('wrong key:', verifyHmac(Buffer.from('wrong-key'), body, signature));
  console.log('malformed:', verifyHmac(key, body, 'sha256=xyz'));
}

module.exports = { verifyHmac };

在已安装 Node.js 的环境中运行:

node hmac-demo.cjs

Windows 11、Node.js v22.22.0 本地实测输出:

original: true
tampered: false
wrong key: false
malformed: false

示例中发送和验证使用同一个进程及演示密钥;另外以独立的已知 HMAC 测试向量和边界输入做了 11 项自动测试,全部通过。这些测试不等于与某个 Webhook 服务联调成功。

接入时容易忽略的细节

  • 验签使用原始请求体字节。 如果协议要求对原文签名,先 JSON.parse() 再 JSON.stringify() 可能改变空格、换行或字段顺序,导致验签失败。应按对方协议保留原始字节,验签成功后再解析和执行业务。
  • 严格检查签名格式。 此示例先检查前缀、总长度和十六进制字符,再解码比较;固定长度的摘要使用 timingSafeEqual。这只保护该比较环节,不保证整个请求处理过程恒定时间。
  • 验签不等于防重放,也不提供加密。 根据提供方协议校验已签名的时间戳和请求 ID,并做幂等或去重;传输仍应使用 HTTPS。示例中的签名只覆盖请求体,因此不能直接加入未受签名保护的时间戳就声称防重放。
  • 密钥要安全管理。 示例字符串公开且不可用于生产;生产环境应使用足够强的随机密钥,通过安全的密钥管理方式保存,并按需轮换。具体签名头名称、编码、签名原文及重试规则,以接入方的协议为准。

验签失败就拒绝处理;验签通过后仍要校验业务字段,避免把消息真实性当成业务数据一定有效。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。