n8n 中文文档

网络钩子

使用Webhook节点创建网络钩子,它可以在事件发生时从应用程序和服务接收数据。它是一个触发节点,这意味着它可以启动 n8n 工作流程。这允许服务连接到 n8n 并运行工作流程。

当您想要接收数据并基于数据运行工作流时,可以使用 Webhook 节点作为工作流的触发器。 Webhook 节点还支持返回工作流结束时生成的数据。这对于构建处理数据并返回结果的工作流程非常有用,例如 API 端点。

Webhook 允许您从没有专用应用程序触发节点的服务触发工作流。

工作流程开发流程

n8n 提供不同的 Webhook URL 用于测试和生产。测试 URL 包括一个 监听测试事件 的选项。有关构建、测试 Webhook 节点以及将其转移到生产环境的更多信息,请参阅 工作流程开发。

节点参数

使用这些参数来配置您的节点。

Webhook URL

Webhook 节点有两个 Webhook URL:测试和生产。 n8n 在节点面板顶部显示 URL。

选择 测试 URL 或 生产 URL 以切换显示哪个 URL n8n。

Webhook 节点的“参数”选项卡中的示例 Webhook URL

  • 测试:当您选择 侦听测试事件 或 执行工作流程(如果工作流程未处于活动状态)时,n8n 会注册测试 Webhook。当您调用 Webhook URL 时,n8n 显示工作流中的数据。
  • 生产:n8n 在您发布工作流程时注册生产 Webhook。使用生产URL时,n8n不显示工作流程中的数据。您仍然可以查看生产执行的工作流程数据:选择工作流程中的 执行 选项卡,然后选择要查看的工作流程执行。

HTTP 方法

Webhook节点支持标准HTTP 请求方法:

  • DELETE
  • GET
  • HEAD
  • PATCH
  • POST
  • PUT

    Webhook 最大负载

    Webhook 最大负载大小为 16MB。如果您是自托管 n8n,则可以使用 endpoint 环境变量 N8N_PAYLOAD_SIZE_MAX.

    更改此设置

路径

默认情况下,该字段包含随机生成的 webhook URL 路径,以避免与其他 webhook 节点冲突。

您可以手动指定URL路径,包括添加路由参数。例如,如果您使用 n8n 来制作 API 原型并想要一致的端点 URL,则可能需要执行此操作。

路径 字段可以采用以下格式:

  • /:variable
  • /path/:variable
  • /:variable/path
  • /:variable1/path/:variable2
  • /:variable1/:variable2

支持的认证方式

您可以要求对调用 Webhook URL 的任何服务进行身份验证。从以下身份验证方法中进行选择:

  • Basic auth 基本身份验证
  • Header auth 标头身份验证
  • JWT auth JWT 身份验证
  • n8n User Auth (OAuth2) n8n 用户身份验证(OAuth2)
  • None 无

有关设置 Basic auth 基本身份验证、Header auth 标头身份验证和 JWT auth JWT 身份验证凭据类型的更多信息,请参阅 Webhook 凭据。

使用 n8n User Auth (OAuth2)

只有登录此 n8n 实例的用户才能调用 Webhook。调用方必须发送由此实例签发的 OAuth2 bearer token。n8n 会将 token 解析为调用用户,并以该用户身份运行此次工作流执行。在此模式下,最终用户凭据会解析到调用用户已连接的账户。

没有 bearer token 的请求按如下方式处理:

  • 来自浏览器的 GET 请求会重定向到 n8n 登录页面。用户登录并同意后,n8n 会将浏览器重定向回 Webhook URL 并运行工作流。
  • 任何其他请求都会收到 401 响应。只有 GET 请求可以重定向。

节点选项中的 OAuth2 Client OAuth2 客户端选项控制此行为。

选择 n8n User Auth (OAuth2) n8n 用户身份验证(OAuth2)后,会出现 Require Workflow Execute Permission 要求工作流执行权限开关。此开关默认开启。开启后,调用用户还必须有权执行工作流所属项目中的该工作流。已登录但没有工作流执行权限的用户无法触发工作流。来自此类用户且带有 bearer token 的请求会收到 403 响应。

调用使用 n8n User Auth (OAuth2) 的 Webhook

n8n 是 Webhook 的 OAuth2 授权服务器。调用方如何获取 bearer token 取决于调用方类型:

  • 浏览器:打开 Webhook URL。n8n 会将你重定向到登录页面和同意页面,然后运行工作流。此方式仅适用于 GET 请求,并且仅当 OAuth2 Client OAuth2 客户端为 Auto-Detect 自动检测或 Browser (Virtual Client) 浏览器(虚拟客户端)时可用。
  • 支持 OAuth 2.1 发现机制的客户端:将 OAuth2 Client OAuth2 客户端设为 Bearer Token Only 仅 bearer token;对于非浏览器请求,也可以使用 Auto-Detect 自动检测,然后发送不带 token 的请求。401 响应包含一个 WWW-Authenticate 标头,其中带有 resource_metadata URL。支持受保护资源 metadata、动态客户端注册和 PKCE 的客户端会使用该 URL 完成登录和同意,无需手动设置。
  • 你自己的脚本或服务:针对 n8n 实例完成 OAuth2 授权码流程: 1. 从 https://<your-n8n-url>/.well-known/oauth-authorization-server 读取授权服务器 metadata。其中列出了注册、授权和 token 端点。 2. 在注册端点注册客户端,或者复用之前注册的客户端。 3. 使用 PKCE (S256) 将用户发送到授权端点,并将 resource 参数设为 Webhook URL 加上 ?method=<HTTP method>,例如 https://<your-n8n-url>/webhook/my-path?method=POST。用户登录并同意。 4. 在 token 端点用授权码换取 access token 和 refresh token。 5. 使用 Authorization: Bearer <access token> 标头调用 Webhook。

每个 token 都与签发它的 Webhook 触发器绑定。为其他触发器或实例的 MCP server 签发的 token 会收到 401 响应。

回复

  • 立即:Webhook 节点返回响应代码和消息工作流程已启动。
  • 当最后一个节点完成时:Webhook 节点返回工作流中执行的最后一个节点的响应代码和数据输出。
  • 使用“响应 Webhook”节点:Webhook 节点按照 响应 Webhook 节点中的定义进行响应。
  • 流式响应:在工作流程过程中启用实时数据流式传输回用户。需要工作流中支持流式传输的节点(例如,人工智能代理 节点)。

响应代码

自定义Webhook节点执行成功后返回的HTTP 响应代码。从常见响应代码中进行选择或创建自定义代码。

响应数据

选择要包含在响应正文中的数据:

  • 所有条目:Webhook 返回数组中最后一个节点的所有条目。
  • 第一个条目 JSON:Webhook 返回 JSON 对象中最后一个节点的第一个条目的 JSON 数据。
  • 第一个条目二进制:Webhook 返回二进制文件中最后一个节点的第一个条目的二进制数据。
  • 无响应正文:Webhook 返回时不带正文。

仅适用于 响应 > 当最后一个节点完成时。

节点选项

选择 添加选项 以查看更多配置选项。可用选项取决于您的节点参数。请参阅该表了解选项的可用性。

  • 允许的来源 (CORS):设置允许的跨域域。输入允许跨源非预检请求的 URL 的逗号分隔列表。使用 *(默认)允许所有来源。
  • 二进制属性:启用此设置允许 Webhook 节点接收二进制数据,例如图像或音频文件。输入要将接收到的文件的数据写入其中的二进制属性的名称。
  • 忽略机器人:忽略来自链接预览器和网络爬虫等机器人的请求。
  • IP 允许列表:启用此选项可限制谁(或什么)可以调用 Webhook 触发器 URL。输入允许的 IP 地址的逗号分隔列表。从允许列表之外的 IP 地址进行访问会引发 403 错误。如果留空,则所有 IP 地址都可以调用 Webhook 触发器 URL。
  • 无响应正文:启用此选项可防止 n8n 发送带有响应的正文。
  • OAuth2 Client OAuth2 客户端:当 Authentication 身份验证为 n8n User Auth (OAuth2) n8n 用户身份验证(OAuth2)时,n8n 处理不带 bearer token 请求的方式。Auto-Detect 自动检测(默认)会将浏览器导航重定向到 n8n 登录页面,并要求所有其他请求提供 bearer token。Bearer Token Only 仅 bearer token始终要求 bearer token,且绝不重定向。Browser (Virtual Client) 浏览器(虚拟客户端)始终将不带 bearer token 的 GET 请求重定向到 n8n 登录页面。只有 GET 请求可以重定向。版本低于 2.2 的 Webhook 节点会继续使用 Bearer Token Only 仅 bearer token行为,直到你设置此选项。
  • Only Run If:根据传入请求计算的表达式。仅当表达式返回 true 时,工作流才会运行。使用 $json 以 { body, headers, params, query } 的形式访问请求。例如,{{ $json.body.campaign_id === 'user-research-invite' }}。不匹配的请求将收到 200 响应,但不会创建执行。如果表达式无法计算,n8n 会记录一条警告并让请求通过而不是阻止它。这在 IP 白名单和身份验证检查之后运行,并适用于测试和生产 Webhook URL。
  • 原始正文:指定 Webhook 节点将以原始格式接收数据,例如 JSON 或 XML。
  • 响应内容类型:选择 Webhook 正文的格式。
  • 响应数据:随响应一起发送自定义数据。
  • 响应标头:在 Webhook 响应中发送额外标头。请参阅 MDN Web 文档 | 响应标头 了解有关响应标头的更多信息。
  • 属性名称:默认情况下,n8n 返回所有可用数据。您可以选择返回特定的 JSON 密钥,以便 n8n 返回值。
选项 所需的节点配置
允许的来源 (CORS) 任何
二元属性

Either:
HTTP 方法 > POST
HTTP 方法 > PATCH
HTTP 方法 > PUT

忽略机器人 任何
IP 允许列表 任何
仅在 任何
属性名称

Both:
响应 > 当最后一个节点完成时
响应数据 > 第一个条目 JSON

无响应 正文 响应 > 立即
OAuth2 Client OAuth2 客户端 Authentication 身份验证 > n8n User Auth (OAuth2) n8n 用户身份验证(OAuth2)
原始主体 任何
响应代码 除“响应”之外的任何代码 > 使用“响应 Webhook”节点
响应内容类型

Both:
响应 > 最后一个节点完成时
响应数据 > 第一个条目 JSON

响应数据 响应 > 立即
响应标头 任何

n8n 如何确保 HTML 响应

提示

功能可用性

n8n 1.103.0 中引入了自动包装 HTML 对 <iframe> 标签中的 webhook 的响应。

从 n8n 1.103.0 开始,n8n 自动将 HTML 响应包装到 <iframe> 标记中的 webhook。这是保护实例用户的安全机制。

这具有以下含义:

  • HTML 在沙盒 iframe 中呈现,而不是直接在父文档中呈现。
  • 尝试访问顶级窗口或本地存储的 JavaScript 代码将会失败。
  • 身份验证标头在沙盒 iframe 中不可用(例如,基本身份验证)。您需要使用替代方法,例如在 HTML 中嵌入短期访问令牌。
  • 相对 URL(例如 <form action="/">)将不起作用。请改用绝对 URL。

模板和示例

浏览 n8n-nodes-base.webhook 集成模板 或 搜索所有模板

FAQ

如何从外部事件触发工作流程?

添加 Webhook 节点作为触发器。它创建一个 网络挂接 URL,在事件发生时从应用程序和服务接收数据,然后使用该数据启动工作流程。它对于没有专用应用程序触发节点的服务非常有用。

测试 Webhook URL 和生产 Webhook URL 有什么区别?

该节点有两个网络钩子 URL。当您选择“监听测试事件”时,测试 URL 将起作用,并在编辑器中显示传入数据。 生产 URL 在您发布工作流程时注册,并且它不会在编辑器中显示数据。您可以在工作流程的 执行 选项卡中查看生产运行。

如何保护 Webhook 的安全?

在支持的身份验证方法中要求身份验证。对于调用 URL 的任何服务,你可以使用 Basic auth 基本身份验证、Header auth 标头身份验证或 JWT auth JWT 身份验证;也可以使用 n8n User Auth (OAuth2),将调用方限制为已登录此 n8n 实例的用户。你还可以使用 IP(s) Allowlist IP 允许列表节点选项限制调用方。请参阅 Webhook 凭据。

常见问题

有关常见问题和建议的解决方案,请参阅 常见问题。

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。