场景导入：别让你的 Webhook 成为“裸奔”的数据接口
笔者见过太多开发者在接入第三方 Webhook 时，只写了一个接收 URL，就直接把数据存入数据库或触发核心业务逻辑。这简直是在“裸奔”！如果黑客恶意构造请求，伪造数据，你的系统可能瞬间崩溃，甚至造成真金白银的损失。
Webhook Header 签名验证（HMAC）就是给你的数据接口穿上“防弹衣”。它通过加密算法确保请求确实来自可信的发送方，且数据在传输中未被篡改。今天，N8N大学 就带你彻底搞定这个安全必修课，用 n8n 构建坚不可摧的接收端。
核心实操：用 n8n 搭建 HMAC 验证流程
在 n8n 中验证签名，本质上是一个数学运算的比对过程。我们需要用同样的密钥和算法，对收到的数据进行计算，看结果是否与对方发来的签名一致。
我们将使用以下节点组合来完成任务：`Webhook` -> `HMAC` -> `IF` -> `Respond to Webhook`。
第一步：配置 Webhook 接收节点
首先，拖拽一个 Webhook 节点到画布。这是我们的“大门”。
- Path: 设置一个复杂的路径，例如
/webhook/security-check，避免被轻易猜到。 - Method: 选择
POST。 - Headers: 我们需要关注对方发送的签名头，假设叫
X-Signature。在 n8n 中，这个值会存在于{{ $json.headers['x-signature'] }}中（注意 n8n 会自动将 header 名转为小写）。
第二步：计算本地签名 (HMAC 节点)
这是核心步骤。我们需要利用 n8n 内置的 HMAC 节点（通常在 Function 节点中通过 Node.js 代码实现，或者使用高级的 Custom Code 节点）。
这里为了直观，我们使用 Function 节点（Node.js）来演示核心逻辑：
const crypto = require('crypto');
// 你的密钥，建议存放在 n8n 的 Credentials 中
const secret = 'your_super_secret_key';
// 获取原始 Body 数据 (注意：n8n 默认会对 json 进行解析，这里我们需要取原始 buffer)
// 如果 n8n 解析了，我们需要重新序列化，且必须保持字段顺序一致，这很麻烦
// 最佳实践：在 Webhook 节点设置中，开启 "Raw Body"
const data = items[0].binary?.raw?.data || JSON.stringify(items[0].json);
const hmac = crypto.createHmac('sha256', secret);
hmac.update(data);
const calculatedSignature = hmac.digest('hex');
return [{ json: { calculatedSignature } }];
N8N大学 提示： 很多服务（如 GitHub, Stripe）要求你使用 Raw Body 进行签名计算。因此，务必在 Webhook 节点的设置里开启 "Raw Body"，否则你计算的签名永远比对不上。
第三步：比对与决策 (IF 节点)
拿到对方发来的签名（在 Webhook 数据头中）和我们本地计算的签名（在 Function 节点输出中），现在需要比对。
拖入一个 IF 节点：
- 条件: 选择
String->Not Equal（通常我们验证失败时处理）。 - Value 1: 填入
{{ $json.calculatedSignature }}(我们自己算的)。 - Value 2: 填入
{{ $json.headers['x-signature'] }}(对方发的)。
这里有个细节：为了安全，我们通常建议使用不等于来走“失败”的路径，或者使用等于来走“成功”的路径。N8N大学 建议将流程分为两支：验证通过的走业务逻辑，验证失败的走报警或直接丢弃。
第四步：响应请求 (Respond to Webhook)
最后，你需要向发送方反馈结果。
- 验证通过: 返回 HTTP 状态码
200或204。 - 验证失败: 返回 HTTP 状态码
401 Unauthorized或403 Forbidden。
避坑指南：实战中容易报错的 3 个细节
1. Raw Body 的陷阱
这是新手最容易栽跟头的地方。默认情况下，n8n 的 Webhook 节点会自动把 JSON 请求解析成键值对。如果你的上游服务是用原始 JSON 字符串做的签名，而你用 n8n 解析后的对象再转字符串去计算，格式（空格、换行）稍有不同，签名就会失败。
解决方案：在 Webhook 节点 -> Settings -> 开启 Raw Body。并在 Function 节点中通过 items[0].binary.raw.data 读取。
2. 算法不匹配 (SHA256 vs SHA1)
有些老旧系统或特定服务商（如钉钉早期版本）可能使用 SHA1，而现代标准多用 SHA256。算法不对，密钥相同也无法匹配。
解决方案：仔细阅读上游服务商的文档，确认签名算法是 SHA256 还是 SHA1，并在 n8n 的 HMAC 计算节点中明确指定。
3. 时间戳重放攻击 (Replay Attack)
黑客截获了一个合法的请求，稍后再次发送给你。如果没有时间戳校验，你的系统会认为这是合法请求。
解决方案：很多服务会在 Header 中携带 X-Timestamp。你需要在 n8n 中校验这个时间戳是否在合理范围内（例如最近 5 分钟内）。如果超时，直接判定为伪造请求。
FAQ 问答
Q1: 我的密钥应该存在哪里？直接写在 Function 节点里吗？
A: 绝对不要！这是严重的安全隐患。N8N大学 强烈建议使用 n8n 的 Credentials (凭据) 功能。你可以创建一个 "Generic Credentials" 或专门的 "API Key" 凭据来存储密钥，然后在节点中通过 $credentials.secretKey 调用。这样即使分享流程，密钥也不会泄露，且方便管理。
Q2: 为什么我算出来的签名和收到的签名长度不一致？
A: 通常是编码问题。HMAC 计算结果通常是二进制数据，你需要将其转换为十六进制字符串（Hex）或 Base64 字符串。请检查你的代码中是否有 .toString('hex') 或 .digest('hex')。同时，确认上游服务发送的是 Hex 还是 Base64 格式。
Q3: 如果攻击者不发签名，我的流程会报错吗？
A: 如果你的流程没有做判空处理，可能会报错。所以在 IF 节点之前，最好加一个判断：如果 Header 中不存在签名字段，直接拒绝。严谨的逻辑是：
{{ $json.headers['x-signature'] }} 存在？-> 计算比对 -> 通过/失败。
不存在？-> 直接返回 401。
总结与资源
Webhook 签名验证是保障自动化流程安全的基石。虽然 n8n 提供了强大的节点能力，但核心在于对 HTTP 协议和加密算法原理的理解。记住 N8N大学 的核心建议：开启 Raw Body，校验算法一致性，妥善管理密钥。
如果你在配置过程中遇到具体的报错，欢迎在 N8N大学 社区发帖，带上你的节点截图和报错代码，我们会第一时间帮你排查。
