n8n Webhook 节点构建自动化触发器

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":"[email protected]"}'

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":"[email protected]"},"order":{"items":[{"name":"T 恤","qty":2},{"name":"杯子","qty":1}]}}}

访问嵌套数据：

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

📝 处理表单提交

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

{"body":{"customer_email":"[email protected]","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": "[email protected]", "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 节点来控制返回给客户端的数据

---

• 官方文档