【n8n教程】：Webhook节点，构建自动化触发器

什么是Webhook？

Webhook 是一个能让外部服务与 n8n 进行实时通信的神奇工具。简单来说，当某个事件发生时，外部服务会立即将数据推送到你的 n8n 工作流，触发自动化流程。

相比传统的"轮询"方式（不断询问是否有新数据），Webhook 更高效、更实时。一旦事件发生，数据就被立即发送给 n8n，n8n 立刻开始处理。

🎯 Webhook的应用场景

• 表单提交处理：用户提交网页表单 → Webhook 接收数据 → n8n 验证并保存
• 支付确认通知：支付平台发送支付成功通知 → 触发订单更新、发票生成
• 第三方系统集成：Shopify 订单、Slack 消息、GitHub 推送等
• 监控和告警：监控系统发送警报 → n8n 通知团队并执行应对措施

核心概念速览

📌 Webhook 节点的两个URL

n8n 为每个 Webhook 节点自动生成两个不同的 URL：

类型	用途	特点
测试URL（Test URL）	开发和测试时使用	临时有效（120秒），数据在编辑器中可见，便于调试
正式URL（Production URL）	部署到生产环境	工作流激活后永久有效，数据不在编辑器显示，需查看执行日志

重要提示：

• 开发时，使用测试 URL 和"Listen for test event"功能
• 测试完成后，激活工作流并切换到正式 URL

🔄 HTTP请求方法

Webhook 支持所有标准 HTTP 方法：

• GET：获取数据（通常用于简单查询）
• POST：发送数据（最常用）
• PUT：完全更新数据
• PATCH：部分更新数据
• DELETE：删除资源

大多数应用场景下，选择 POST 就够了。

📊 响应模式

Webhook 节点有三种响应方式：

响应模式	说明
立即响应（Immediately）	立即返回 "Workflow got started" 消息，工作流继续后台处理
最后节点完成时响应（When Last Node Finishes）	等待整个工作流完成，返回最后一个节点的输出
使用 Respond to Webhook 节点	完全控制响应内容、状态码和请求头

快速开始

第一步：创建工作流并添加Webhook节点

1. 进入 n8n 仪表板，创建一个新工作流
2. 点击"Add first step"
3. 搜索并选择"Webhook"节点
4. 该节点自动成为工作流的触发器

第二步：配置基本参数

在 Webhook 节点的设置面板中：

HTTP 方法：POST（根据你的需求选择）
路径：例如 /webhook/process-form
认证方式：None（开发时），生产环境建议用 Basic Auth、Header Auth 或 JWT

获取你的 Webhook URL：

• 点击节点上方的"Test URL"或"Production URL"，n8n 会为你生成完整链接
• 复制这个链接，发送给外部服务

第三步：测试Webhook

1. 在 Webhook 节点中，点击**"Listen for test event"**按钮
2. 该按钮变成蓝色，表示正在监听（有效期120秒）
3. 使用 curl 或 Postman 向你的 Webhook URL 发送测试请求：

curl -X POST 'https://your-n8n.url/webhook/process-form' \
  -H 'Content-Type: application/json' \
  -d '{"name":"张三","email":"zhangsan@example.com"}'

4. 返回 n8n，你会看到接收到的数据显示在节点的输出面板中

第四步：处理数据

在 Webhook 节点后面添加其他节点来处理接收到的数据：

• Set 节点：转换数据格式
• Google Sheets 节点：将数据写入表格
• Slack 节点：发送通知
• Code 节点：自定义处理逻辑

参数详解

🔑 访问传入的数据

当 Webhook 接收请求时，n8n 会将数据解析成 JSON 对象，包含以下部分：

数据来源	表达式	例子
查询参数（?key=value）	`{{ $json.query.key }}`	`{{ $json.query.user_id }}`
请求头（Headers）	`{{ $json.headers['header-name'] }}`	`{{ $json.headers['content-type'] }}`
URL路径参数（/:id）	`{{ $json.params.id }}`	`{{ $json.params.user_id }}`
请求体（Body）	`{{ $json.body }}` 或 `{{ $json.body.field }}`	`{{ $json.body.customer_name }}`

⚠️ 访问请求头的注意事项

JavaScript 不支持对象属性名中的连字符。访问含有连字符的请求头时，需要用方括号表示法：

❌ 错误：{{ $json.headers.user-agent }}
✅ 正确：{{ $json.headers['user-agent'] }}

📥 接收JSON数据

当请求的 Content-Type 为 application/json 时，n8n 会自动解析为 JSON 对象：

{
  "body": {
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "order": {
      "items": [
        {"name": "T恤", "qty": 2},
        {"name": "杯子", "qty": 1}
      ]
    }
  }
}

访问嵌套数据：

{{ $json.body.customer.name }}        // 获取客户名字
{{ $json.body.order.items[0].name }}  // 获取第一个商品名称

📝 处理表单提交

从 HTML 表单提交来的数据会自动解析到 body 中：

{
  "body": {
    "customer_email": "user@example.com",
    "customer_name": "李四",
    "product_id": "prod_12345"
  }
}

使用 Set 节点提取数据：

{{ $json.body.customer_email }}

🛡️ 支持的认证方式

认证类型	用途	安全性
None	内部工具、本地开发	⚠️ 无保护
Basic Auth	信任的服务商	✅ 基础保护
Header Auth	自定义 API 密钥	✅✅ 中等保护
JWT Auth	移动应用、公开 API	✅✅✅ 高级保护

实战案例

📋 案例：构建表单提交自动保存系统

这个工作流接收表单数据，验证后保存到数据库，最后向用户发送确认邮件。

工作流流程：

1. Webhook 接收表单提交
2. 验证邮箱格式
3. 保存到数据库（或 Google Sheets）
4. 发送确认邮件

工作流 JSON 代码（复制到 n8n 导入）：

{
  "nodes": [
    {
      "parameters": {
        "path": "form-submit",
        "httpMethod": "POST"
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "values": {
          "string": [
            {
              "name": "email",
              "value": "={{ $json.body.email }}"
            },
            {
              "name": "name",
              "value": "={{ $json.body.name }}"
            },
            {
              "name": "message",
              "value": "={{ $json.body.message }}"
            },
            {
              "name": "submitted_at",
              "value": "={{ new Date().toISOString() }}"
            }
          ]
        },
        "keepOnlySet": true
      },
      "name": "Set",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [450, 300]
    },
    {
      "parameters": {
        "jsCode": "const emailRegex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\nif (!emailRegex.test(items[0].json.email)) {\n  throw new Error('Invalid email format');\n}\nreturn items;"
      },
      "name": "Validate Email",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [650, 300]
    },
    {
      "parameters": {
        "documentId": {
          "__rl": true,
          "value": "your-google-sheet-id",
          "resource": "doc"
        },
        "sheetName": "responses",
        "columns": {
          "mappingMode": "defineBelow",
          "value": [
            {
              "header": "email",
              "key": "email"
            },
            {
              "header": "name",
              "key": "name"
            },
            {
              "header": "message",
              "key": "message"
            },
            {
              "header": "submitted_at",
              "key": "submitted_at"
            }
          ]
        }
      },
      "name": "Save to Google Sheets",
      "type": "n8n-nodes-base.googleSheets",
      "typeVersion": 4.4,
      "position": [850, 300]
    },
    {
      "parameters": {
        "respondWith": "allIncomingItems"
      },
      "name": "Respond to Webhook",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.2,
      "position": [1050, 300]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{"node": "Set", "type": "main", "index": 0}]]
    },
    "Set": {
      "main": [[{"node": "Validate Email", "type": "main", "index": 0}]]
    },
    "Validate Email": {
      "main": [[{"node": "Save to Google Sheets", "type": "main", "index": 0}]]
    },
    "Save to Google Sheets": {
      "main": [[{"node": "Respond to Webhook", "type": "main", "index": 0}]]
    }
  }
}

如何使用这个工作流：

1. 将上面的 JSON 代码复制到剪贴板
2. 在 n8n 中，点击"Import workflow"，选择"From clipboard"，粘贴代码
3. 修改 Google Sheets ID（替换你自己的）
4. 激活工作流并获取 Production URL
5. 在你的网站表单的 action 属性中填入这个 URL

测试请求（使用 curl）：

curl -X POST 'https://your-n8n-instance/webhook/form-submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "王五",
    "email": "wangwu@example.com",
    "message": "这是一条测试消息"
  }'

预期响应：

{
  "success": true,
  "message": "Form submitted successfully",
  "timestamp": "2024-12-02T15:30:00Z"
}

常见问题解决

❓ Q1：Webhook 测试时一切正常，但激活后收不到数据

原因：使用了测试 URL 而不是正式 URL

解决：

1. 激活工作流
2. 复制 Production URL（不是 Test URL）
3. 更新外部服务中的 webhook URL 配置

❓ Q2：同时接收多种 HTTP 方法（GET 和 POST）

解决步骤：

1. 打开 Webhook 节点的"Settings"
2. 启用"Allow Multiple HTTP Methods"
3. 返回参数设置，在 HTTP Methods 字段中选择需要的方法
4. 现在 Webhook 节点会为每个方法创建独立的输出分支

❓ Q3：IP 地址白名单设置后无法连接

原因：n8n 可能运行在反向代理后面

解决：
设置环境变量：

N8N_PROXY_HOPS=1

如果有多个反向代理，将 1 改为相应数字。

❓ Q4：如何返回自定义的字符串响应而不是 JSON？

解决：

1. 在 Webhook 节点中，设置"Response Mode"为"When Last Node Finishes"
2. 设置"Response Data"为"First Entry JSON"
3. 添加"Add Option" → "Property Name"，输入属性名（如 data）
4. 在前面添加 Set 节点 或 Edit Fields 节点
5. 创建一个同名的字符串字段
6. 启用"Keep only set"选项

❓ Q5：webhook 最大负载大小是多少？

答：默认限制为 16MB

如果是自托管 n8n，可以通过环境变量调整：

N8N_PAYLOAD_SIZE_MAX=300mb

❓ Q6：相同路径和方法的 webhook 冲突

错误信息："The path and method you chose are already in use"

原因：n8n 不允许注册相同路径和方法的多个 webhook

解决：

• 停用冲突的工作流，或
• 改变其中一个 webhook 的路径或 HTTP 方法

进阶技巧

🔄 处理长时间运行的工作流

当工作流可能超过 100 秒时（n8n Cloud 的超时限制），可以采用异步轮询模式：

1. 第一个 Webhook：立即返回一个 jobId
2. 后台处理：工作流继续运行，处理请求
3. 第二个 Webhook：客户端定期调用这个端点，查询处理结果
4. 返回结果：处理完成后返回最终结果

🛡️ 不要忘记生产环境的安全措施

• ✅ 启用 Header Auth 或 JWT Auth
• ✅ 配置 IP 白名单
• ✅ 设置 CORS 限制
• ✅ 验证所有输入数据
• ✅ 使用 HTTPS（不是 HTTP）

总结

• Webhook 是 n8n 中强大的触发器，能让外部服务和 n8n 实时通信
• 开发时用测试 URL，部署时用正式 URL
• 充分利用 n8n 的表达式语法（$json.body、$json.query 等）来访问数据
• 在生产环境中不要忘记安全认证
• 合理使用响应模式和 Respond to Webhook 节点来控制返回给客户端的数据

• 官方文档^[1]
• n8n 系列教程^[2]

引用链接

[1] 官方文档: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/
[2] n8n 系列教程: https://www.undsky.com/blog/?category=n8n%E6%95%99%E7%A8%8B#