使用 HMAC256 安全校验 GitHub Webhook - n8n 工作流

DevOps 和安全工程师： 需要确保传入的自动化事件真实性的专业人员。
n8n 高级用户： 任何构建需要强大安全检查的对公网开放的 Webhook 的人。
开发者： 在集成 GitHub 流程并为部署寻找可靠、安全 n8n 模板的用户。
自动化专家： 需要在其 n8n 工作流中实现高级核心逻辑流程控制的人员。

对于安全的自动化来说，Webhook 请求的完整性和真实性至关重要。如果没有签名验证，您的 n8n 工作流可能会受到未授权或恶意请求的攻击。这个基础的 n8n 工作流通过实现 HMAC-SHA256 验证（完全按照 GitHub 的推荐做法），提供了一个强大的安全层。此 n8n 模板的核心价值在于它能够使用共享密钥，复现 GitHub 执行的签名计算过程。这种设置确保只有在收到源自您配置的 GitHub 仓库的、经过验证且未被篡改的数据时，下游的 n8n 节点才会执行。这种方法使其成为与源代码管理平台集成的最安全、最可靠的 n8n 模板之一。

安全流程始于 GitHub Webhook n8n 触发器，它会监听传入的 POST 请求。收到请求后，工作流立即将请求体（payload）路由到“计算 HMAC256 (Compute HMAC256)” n8n 节点。该节点使用 GitHub Webhook 设置期间定义的密钥，对原始 JSON 主体计算 HMAC-SHA256 签名。随后的“验证 HMAC256 (Validate HMAC256 If)” n8n 节点会执行一个关键的安全检查：它将新计算出的签名与传入的 x-hub-signature-256 标头中提供的值（提取哈希后）进行比较。

如果验证成功（签名匹配），工作流会通过“响应 Webhook (Respond to Webhook)” n8n 节点发送一个 200 OK 响应，确认请求的真实性，并允许 n8n 工作流的其余部分继续执行（例如，执行占位的 GitHub n8n 节点）。

如果验证失败，工作流会立即通过另一个“响应 Webhook (Respond to Webhook)” n8n 节点发送 401 Unauthorized 响应，向 GitHub 发出失败信号。随后，“停止并报错 (Stop and Error)” n8n 节点会终止执行并记录安全故障，确保此 n8n 工作流中没有未授权的代码运行。

1. 导入 n8n 工作流： 复制提供的 JSON 并直接导入到您的 n8n 实例中。


2. 设置 Webhook： 记下 GitHub Webhook n8n 触发器提供的路径（例如 /github-test）。在您的 GitHub 仓库的 Webhook 设置中使用此完整 URL。


3. 设置密钥： 至关重要的一步，更新 计算 HMAC256 (Compute HMAC256) n8n 节点中的 Secret 参数。此值必须与您在 GitHub Webhook 设置中配置的密钥完全一致。


4. 配置凭据： 如果您打算使用此 n8n 模板的这部分来进行进一步的自动化，请确保占位的 获取仓库信息 (Get the profile of a repository) GitHub n8n 节点已配置了有效的 GitHub API 凭据。


5. 激活： 将 n8n 工作流设置为激活状态。安全检查现在对所有传入的 Webhook 调用生效。

GitHub Webhook (n8n 触发器)： 此安全 n8n 工作流的入口点。它监听特定路径上传入的 GitHub POST 请求，并配置为等待后续的响应节点。
计算 HMAC256 (Compute HMAC256) (Crypto n8n 节点)： 关键的安全组件。它使用 SHA256 哈希类型和 HMAC 操作，根据 JSON.stringify($json.body) 计算签名。结果存储在 signature-256 中。
验证 HMAC256 (Validate HMAC256 If) (n8n 节点)： 执行关键的比较。它检查计算出的值 ($json['signature-256']) 是否等于从 x-hub-signature-256 标头中提取的值。此逻辑控制着整个 n8n 工作流的走向。
响应 200 OK 和 响应 401 Unauthorized (Respond to Webhook n8n 节点)： 这些节点处理与 GitHub 的回传通信，确认验证过程的成功 (200) 或拒绝 (401)。
停止并报错 (Stop and Error) (n8n 节点)： 用于未授权路径 (401) 上，以明确记录失败情况并阻止 n8n 工作流继续执行，这对于监控安全问题非常有益。
获取仓库信息 (Get the profile of a repository) (GitHub n8n 节点)： Webhook 经验证后，所有后续授权业务逻辑的占位符。请用您需要的自动化步骤替换此 n8n 节点。