Node.js 验证 Webhook 签名:先保留原始请求体
【摘要】 接收 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)