Webhook 集成实战：把外部事件接进 AI 工作流

Webhook 不是一个网址，而是一份事件契约

Webhook 让外部系统在事件发生时主动调用 N8N，例如订单支付、工单创建或代码发布。它比定时轮询及时，也减少无效请求，但生产实现不能止于复制 Webhook 节点生成的 URL。发送方和接收方必须约定请求方法、认证方式、事件类型、唯一事件 ID、时间戳、数据结构、响应码、超时与重试策略。

建议入口只接收稳定的“信封”结构，业务字段放在 data 中：

{
  "eventId": "evt_20260908_001",
  "eventType": "order.paid",
  "occurredAt": "2026-09-08T09:30:00Z",
  "source": "storefront",
  "data": {
    "orderId": "ord_8848",
    "customerMessage": "请周五前送到，门卫可代收",
    "amount": 39900,
    "currency": "CNY"
  }
}

eventId 用于幂等，eventType 用于路由，occurredAt 用于防重放，source 用于选择密钥和审计。金额应使用最小货币单位的整数，避免浮点误差。协议应明确新增字段向后兼容，而删除字段、改类型或改变枚举需要版本升级。

配置 Webhook 节点与响应方式

新建工作流后加入 Webhook 节点，生产事件通常选 POST，并设置难以猜测但仍需鉴权的路径。N8N 提供测试地址和生产地址：测试地址只在监听测试事件时可用，生产地址要求工作流已激活。联调时误把测试地址交给发送方，是“昨天能通、今天 404”的常见原因。

将响应模式设为使用 Respond to Webhook 节点，便于在不同校验结果下返回明确状态。入口依次连接“提取原始请求信息”“校验签名”“校验结构”“登记事件”。拒绝请求时不要继续进入模型节点。推荐语义如下：格式或必填字段错误返回 400，签名错误返回 401 或 403，重复但已受理的事件仍返回 200，内部暂时不可用返回 503。不要在响应中暴露堆栈、密钥、数据库错误或模型提示词。

多数发送方只等待几秒。不要让它同步等待 AI 推理、数据库写入和多渠道通知。入口完成认证、结构校验和事件持久化后立即返回 202，再由 Execute Workflow 调用子工作流，或由队列消费者异步处理。若部署模式无法保证“触发子流程”与“返回响应”之间可靠交接，先把事件写入数据库或消息队列；只有写入成功才确认接收。

用原始请求体校验签名

常见方案是发送方用共享密钥对“时间戳 + 分隔符 + 原始请求体”计算 HMAC-SHA256，并在请求头传递时间戳和签名。接收方必须使用完全相同的原始字节序列，不能对解析后的 JSON 再序列化：字段顺序、空格或转义变化都会导致签名不同。

在 Webhook 节点启用保留原始请求体的能力，具体字段名应以当前 N8N 版本实际输出为准。用 Crypto 节点或 Code 节点计算期望签名，并采用恒定时间比较。密钥放在 Credentials 或运行环境的 secrets 中，不能写进节点代码、示例数据和执行日志。下面展示核心逻辑，输入字段需按实际部署映射：

const crypto = require('crypto');
const timestamp = String($json.headers['x-event-timestamp'] || '');
const received = String($json.headers['x-event-signature'] || '')
  .replace(/^sha256=/, '');
const rawBody = $json.rawBody;

if (!timestamp || !received || typeof rawBody !== 'string') {
throw new Error('SIGNATURE_INPUT_MISSING');
}

const age = Math.abs(Date.now() - Date.parse(timestamp));
if (!Number.isFinite(age) || age > 5 * 60 * 1000) {
throw new Error('SIGNATURE_TIMESTAMP_EXPIRED');
}

const expected = crypto
.createHmac('sha256', $env.WEBHOOK_SIGNING_SECRET)
.update(${timestamp}.${rawBody}, 'utf8')
.digest('hex');

const a = Buffer.from(expected, 'hex');
const b = Buffer.from(received, 'hex');
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
throw new Error('SIGNATURE_INVALID');
}
return $input.all();
`

生产环境还应通过反向代理限制请求体大小、启用 TLS，并在密钥轮换期间允许“当前密钥 + 上一把密钥”短暂并存。IP 白名单只能作为附加防护，因为发送方出口可能变化，也不能证明请求内容没有被篡改。

先验证结构，再让 AI 看数据

签名有效只表示请求来自持有密钥的一方，并不代表字段可用。用 IF、Switch 或 Code 节点检查 eventId、事件类型、时间格式和业务字段。设置允许的事件类型白名单；限制字符串长度、数组数量和嵌套深度；金额验证为非负整数；未知类型记录后安全结束。外部文本进入提示词前，应明确标为“不可信数据”，并只传完成任务所需的字段。

可以在 Set 节点生成内部统一对象，避免后续每个节点都依赖供应商字段：

{
  "requestId": "={{ $json.body.eventId }}",
  "kind": "={{ $json.body.eventType }}",
  "orderId": "={{ $json.body.data.orderId }}",
  "message": "={{ $json.body.data.customerMessage || '' }}",
  "receivedAt": "={{ $now.toISO() }}"
}

这一步也是脱敏边界。模型若只需判断配送备注，就不要传姓名、电话、地址和完整订单。日志同样只保留 requestId、阶段、耗时、结果类别和安全错误码。

幂等：让同一事件执行多次仍只有一次效果

Webhook 发送方遇到超时、连接断开或 5xx 通常会重试；N8N 执行成功但响应在网络中丢失时，发送方也会重发。因此“正常情况下只发一次”不是可靠假设。以 source + eventId + eventType 作为幂等键，在数据库建立唯一约束，并保存 received、processing、completed、failed 等状态。

入口用原子插入登记事件。如果唯一约束冲突，查询原记录：已完成则直接确认；处理中则确认已接收；失败且允许恢复时，把它交给受控重放流程，而不是自动并发再跑一遍。不能用“先查询、未发现、再插入”代替唯一约束，因为两个并发请求可能同时通过查询。

通知等副作用也要有自己的幂等键，例如 eventId:ops_notification:v1。这样即使模型步骤完成后工作流崩溃，恢复执行也不会重复发消息。数据库状态更新应记录阶段结果，而不是只写一个模糊的成功布尔值。

重试：只重试可能恢复的错误

HTTP 429、连接超时和部分 5xx 可以有限重试，采用指数退避并加入随机抖动，例如约 2 秒、5 秒、12 秒。400 参数错误、401 鉴权失败和模型输出不合规不会因原样重试而恢复。每次尝试保存 attempt 和错误类别，达到上限后进入死信表并告警。

尤其要区分“请求失败”和“结果未知”。通知接口在客户端超时前可能已经成功接收，此时盲目重试会重复发送。优先向下游传幂等键；若下游不支持，则在重试前查询发送状态，或接受人工确认。N8N 的节点自动重试适合无副作用的短暂故障，复杂补偿应放到错误工作流或专门的恢复工作流中。

完整示例：订单事件到 AI 判断再通知

主工作流可按以下顺序编排：Webhook 接收订单事件；Code 节点校验 HMAC 和时间窗；结构校验拒绝非法输入；Postgres 原子登记 eventId；Respond to Webhook 返回 202；Execute Workflow 把标准化对象交给订单处理子流程。

子流程先从订单系统读取可信订单状态，确认事件对应的订单确实已支付。随后把经过最小化处理的客户备注交给 AI，要求输出严格结构：

{
  "category": "delivery_instruction",
  "risk": "low",
  "summary": "客户希望周五前送达，可由门卫代收",
  "needsHuman": false
}

为输出定义枚举、长度和布尔类型，使用结构化输出解析器。验证失败时最多进行一次仅针对格式的修复；仍失败则设置 needsHuman: true，不能让不确定文本直接驱动退款、改价或改地址。用 Switch 按 risk 与 needsHuman 分支：普通备注写入订单时间线，高风险或含糊请求创建人工任务，再通过企业消息或邮件通知。通知内容包含订单 ID、摘要、事件时间和后台链接，不包含签名头或多余个人数据。

最后在数据库记录模型版本、分类结果、通知 ID 和完成时间。若通知失败，事件状态标记为 notification_pending，恢复流程只补发通知，不再次调用模型。错误工作流接收 execution ID、requestId、失败阶段和安全错误摘要，便于值班人员定位。

上线前的验证清单

先用固定夹具测试正确签名、错误签名、过期时间戳、缺失字段、未知事件类型和超大正文。然后连续发送两次相同 eventId，确认只有一条业务记录和一次通知。模拟模型超时、通知接口 429、数据库短暂断开以及“下游成功但客户端超时”，检查重试是否有上限且不会重复副作用。

观察执行记录时，确认秘密与个人数据已脱敏；确认入口能在发送方超时之前返回；确认死信事件可按 requestId 安全重放；确认停用工作流或轮换密钥时有操作手册。上线后监控接收量、鉴权失败率、重复率、处理延迟、死信数和各阶段错误率。只有当事件可追踪、可重放且重复执行无害时，这个 Webhook 才真正具备生产可靠性。