n8n Webhook 教程：接收外部数据并返回响应

Webhook 可以让外部服务在事件发生时“主动通知”n8n。例如：

网站表单有人提交
支付平台通知付款成功
GitHub 有新的 Pull Request
自己编写的程序想触发一个 n8n 工作流

n8n 的 Webhook 节点会生成一个 URL，任何发送到该 URL 的 HTTP 请求都会启动工作流。

创建 Webhook

新建工作流，将第一个节点设为 Webhook。
设置：
- HTTP Method：通常为 POST
- Path：URL 路径，例如 contact-form
- Respond：何时响应（见下方说明）

节点上方会显示两个 URL：

URL	格式	何时有效
Test URL	`https://你的域名/webhook-test/contact-form`	点击“Listen for test event”后，接收一次请求
Production URL	`https://你的域名/webhook/contact-form`	工作流发布后

Webhook 节点显示 Test URL 和 Production URL — Webhook 节点：可以在上方切换 Test URL 和 Production URL。这里显示的 URL 是 localhost，说明尚未设置外部访问 URL

最常见的错误：把 Test URL 配置到外部服务，导致工作流发布后收不到数据。正式使用时，请务必改用 Production URL。

测试

点击 Listen for test event。
在终端中发送请求：

curl -X POST https://你的域名/webhook-test/contact-form \
  -H "Content-Type: application/json" \
  -d '{"name": "王小明", "email": "ming@example.com", "message": "想咨询报价"}'

Webhook 节点的 OUTPUT 中会显示收到的数据：

{
  "headers": { "content-type": "application/json", "...": "..." },
  "params": {},
  "query": {},
  "body": {
    "name": "王小明",
    "email": "ming@example.com",
    "message": "想咨询报价"
  }
}

后续节点可以用 {{ $json.body.name }} 读取发送来的数据，URL 参数（?id=123）则在 {{ $json.query.id }} 中。

响应方式

Respond 选项决定 n8n 何时响应调用方，以及返回什么内容：

选项	行为
Immediately	收到请求后立即响应，工作流在后台继续运行
When Last Node Finishes	等待整个工作流运行完毕，返回最后一个节点的数据
Using 'Respond to Webhook' Node	由工作流中的 Respond to Webhook 节点决定响应内容

调用方只需要知道“已收到”时（例如支付通知），选择 Immediately；需要返回处理结果时（例如将其做成 API），使用 Respond to Webhook 节点。

用 n8n 创建一个简单的 API

[Webhook GET /price] ─▶ [Google Sheets 查询] ─▶ [Respond to Webhook]

由 Webhook、Edit Fields 和 Respond to Webhook 组成的工作流 — Webhook → 整理数据 → Respond to Webhook 返回 JSON

Respond to Webhook 节点可以设置：

Respond With：JSON、文本、二进制文件、重定向
Response Code：例如 200、404
Response Headers：例如 CORS 标头



{ "product": "{{ $json.name }}", "price": {{ $json.price }} }

路径参数

Path 可以包含变量：

orders/:orderId

调用 /webhook/orders/A123 时，{{ $json.params.orderId }} 的值就是 A123。

验证请求

Production URL 是公开的，任何知道 URL 的人都能调用。可以通过以下方式保护：

Authentication 选项：Basic Auth、Header Auth、JWT Auth。例如，Header Auth 设置名称 X-API-Key 后，调用方必须携带正确的值。
验证签名：许多服务（Stripe、GitHub、LINE 等）会在 Header 中附带签名，可以用 Code 节点验证。
IP 白名单：在 Webhook 的 Options 中设置 IP(s) Whitelist。
使用不易猜到的随机字符串作为路径。

接收文件

表单上传文件时（multipart/form-data），文件会出现在 binary 数据中，可以直接连接到 Google Drive、Extract from File 等节点。

让外部服务能够访问你的 n8n

外部服务必须能够通过网络连接到 n8n：

正式部署：使用具有域名和 HTTPS 的服务器，并设置正确的 Webhook URL 环境变量，否则 n8n 显示的 URL 会是 http://localhost:5678/...。参见自托管部署。
本地测试：可以使用 Cloudflare Tunnel、ngrok 等工具，暂时将本机的 5678 端口开放给外部访问。

常见问题

404：The requested webhook is not registered

使用 Test URL 时：没有先点击 Listen for test event，或者已经接收过一次请求。
使用 Production URL 时：工作流尚未发布。
HTTP 方法不匹配（设置为 POST，却使用 GET 调用）。

收到的 body 为空

确认调用方发送了 Content-Type: application/json 标头。

外部服务提示超时

你选择了 When Last Node Finishes，但工作流运行时间太长。可以改为 Immediately，或缩短工作流。

更新于 2026年10月12日