n8n 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 对象，包含以下部分：

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

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 }}

🛡️ 支持的认证方式

实战案例

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

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

工作流流程：

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 节点来控制返回给客户端的数据

• 官方文档