HTTP Webhook 身份验证

先决条件

您的 Webhook 提供程序可能需要握手。有关如何配置质询验证的详细信息，请参阅Webhook 质询验证部分。

根据创建触发器的位置，生成的 Webhook URL 将出现在HTTP Webhook触发器活动或触发器创建页面中，但仅在成功创建连接之后。为避免失败，在 UiPath Orchestrator 中成功创建工作流或触发器后，请将 Webhook URL 粘贴到您的应用程序中。

创建 HTTP Webhook 连接

1. 从产品启动器中选择“Orchestrator”。

2. 选择一个文件夹，然后导航到“连接”选项卡。

3. 选择“添加连接”。

4. 要打开连接创建页面，请从列表中选择连接器。您可以使用搜索栏查找连接器。

5. 在“此 Webhook 适用的应用程序”字段中，输入 Webhook 应用程序的描述性名称，您可以轻松识别此连接所代表的供应商或集成。此值将成为连接标识符。

6. (Optional) Configure header-based authentication.

   If you want UiPath to validate every incoming webhook request, from the Authentication Type dropdown select Header Based Authentication, then specify:

   • Header key — the HTTP header the vendor uses to send the credential (for example, X-API-Key or X-API-Secret).
   • Header value — the secret value the vendor sends in that header (for example, a1b2c3d4e5f6789...). This field is masked and stored securely. You can also use a credential asset for this field.

   Configure the same header key and value in the vendor's webhook settings. If the values don't match at runtime, UiPath rejects the request with HTTP 401.

   For more information, see Webhook header authentication.

7. 配置质询位置
   选择供应商发送质询令牌的方式，以便 UiPath 可以正确响应：

   • “无质询” - 供应商不需要握手，您可以继续连接。
   • 查询参数（例如?challenge=... ）
   • JSON 正文（带有{ "challenge": "..." } POST）
   • 标头（例如X-Hub-Challenge ）

8. 配置质询验证并连接
   If the vendor requires a handshake, enter the challenge verification that matches the vendor's pattern (which field/header/query to read and how to echo/validate it). When configuration is complete, select Connect.

   Where available, select the menu next to a field and choose Use credential asset or Use Orchestrator asset to reference an Orchestrator asset instead of entering the value directly. For more information, see Use credential assets for connections.

提示：

• 使用包含供应商和环境的名称（例如 Stripe-prod 或 Slack-staging）以避免混淆。
• 如果您不确定供应商使用哪种质询模式，请查看其 Webhook 文档或运行测试注册以检查握手请求。

Webhook 质询验证

一些供应商要求在开始发送实际事件之前验证 Webhook URL。这是通过使用质询-响应机制来完成的。在注册 Webhook 时，供应商会发送特殊质询请求，并且端点必须完全按预期响应。

HTTP Webhook 连接器通过Webhook 挑战框架支持这些验证流程，从而允许您配置 UiPath 读取和响应供应商挑战的方式。

质询验证支持

UiPath 支持两种类型的供应商 Webhook 行为：

• 不使用质询验证的供应商
• 在激活 Webhook 之前需要质询握手的供应商

这可确保与简单以及具有更高级安全要求的提供程序兼容。

当供应商不使用质询验证时

许多应用程序只是接受 Webhook URL 并立即开始传递事件。
对于这些供应商：

• 用户只需创建或选择一个连接。
• 复制Webhook URL（URL） 。
• 将其粘贴到供应商的 Webhook 配置中。

不需要其他步骤。一旦供应商开始发送事件，Webhook 将变为活动状态。

这是最常见也是最简单的场景，UiPath 可以无缝处理。

每当供应商确实要求质询验证时，

一些供应商在启用 Webhook URL 之前会发送质询请求以验证该 URL。
在这些情况下：

• 用户必须在 HTTP Webhook 连接中配置质询响应。
• UiPath 侦听供应商的质询请求。
• UiPath 根据配置自动返回正确的质询值。
• 供应商验证了响应后，普通事件将开始流动。

由于供应商发送质询的方式（查询参数、JSON 正文、标头等）各不相同，UiPath 的配置允许用户处理其中的任何模式。

这可确保与强制执行安全握手的 Webhook 提供程序兼容，例如 Slack、Meta ( Facebook/Instagram)、S Stripe 等。

配置质询验证

您可以使用四个参数配置质询行为：

• 挑战密钥
  包含质询值的字段/键。用于检测质询请求（不得为 null）。

• 挑战地点
  其中键出现的位置：

  • 正文
  • 查询参数
  • 页眉

• 质询响应内容类型
  返回给供应商的响应格式：

  • 文本/纯文本
  • application/json

• 质询响应格式
  定义返回的值（通常是质询密钥本身）。
  UiPath 从传入的质询中提取值，并做出相应的响应。

质询配置示例

通用示例

传入的请求

 {
  "challenge": "ABC123"
 }

配置

• 挑战密钥： challenge != null
• 挑战位置：正文
• 响应类型： text/plain
• 响应格式： challenge

响应

ABC123

WhatsApp 质询验证示例

WhatsApp 将基于查询参数的质询方法与Hub.challenge结合使用。

配置

参数	值
挑战密钥	hub.challenge != null
挑战地点	查询参数
质询响应内容类型	text/plain
质询响应格式	hub.challenge

供应商请求

GET https://your-webhook-url?hub.challenge=1234567890

预期 UiPath 响应

HTTP/1.1 200 OK
Content-Type: text/plain

1234567890

这将确认所有权，然后 WhatsApp 开始发送实际的 Webhook 事件。

摘要 — 通用与 WhatsApp

步骤	一般示例	WhatsApp 示例
挑战地点	正文/查询/标头	查询
密钥格式	简单键（例如challenge ）	带有点（“ hub.challenge ”）的密钥
响应类型	text/纯文本 或 application/json	文本/纯文本
响应值	键的值	“ hub.challenge ”的值
方法	POST 或 GET	仅获取

按供应商模式划分的示例

示例 1：包含文本响应的简单正文质询

供应商发送

{"challenge":"abc123","type":"url_verification"}

字段	值
挑战地点	Body
质询键	challenge
质询响应内容类型	text
质询响应格式	challenge

响应： abc123 （文本/纯文本、200）

示例 2：带有文本响应的查询参数质询

供应商发送

GET /webhook?challenge=CHALLENGE_STRING

字段	值
挑战地点	Query Parameter
质询键	challenge
质询响应内容类型	text
质询响应格式	challenge

响应： CHALLENGE_STRING （文本/纯文本、200）

示例 3：带有 JSON 响应的正文质询

供应商发送

{"challenge":"abc123"}

字段	值
挑战地点	Body
质询键	challenge
质询响应内容类型	json
质询响应格式	{ "challenge": "challenge" }

响应： {"challenge":"abc123"} (application/json，200)

示例 4：具有文本响应的嵌套式正文路径（例如verification.token ）

供应商发送

{"verification":{"token":"abc123"}}

字段	值
挑战地点	Body
质询键	verification.token
质询响应内容类型	text
质询响应格式	verification.token

响应： abc123 （文本/纯文本、200）

示例 5：具有 JSON 响应的深度嵌套路径

供应商发送

{"event":{"challenge":"abc123","type":"verify"}}

字段	值
挑战地点	Body
质询键	event.challenge
质询响应内容类型	json
质询响应格式	{ "result": "event.challenge" }

响应： {"result":"abc123"} (application/json，200)

示例 6：带有文本响应的基于标头的质询（带连字符的标头名称）

供应商发送

POST /webhook x-webhook-challenge: abc123

字段	值
挑战地点	Header
质询键	"x-webhook-challenge"
质询响应内容类型	text
质询响应格式	"x-webhook-challenge"

响应： abc123 （文本/纯文本、200）

备注：

标头名称包含连字符，在解析上下文中，连字符可能会被解释为运算符。用双引号（例如"x-webhook-challenge" ）将标识符括起来，可确保将其视为文本密钥名称。请始终使用双引号将包含连字符 、点 或其他特殊字符的标识符括起来。

示例 7：使用不同响应键的布尔值检测

供应商发送

{"type":"url_verification","challenge":"abc","token":"legacytoken"}

想要按type字段检测，但以challenge值响应。

字段	值
挑战地点	body
质询键	type == URL 验证
质询响应内容类型	json
质询响应格式	{ "challenge": "challenge" }

响应： {"challenge":"abc"} (application/json，200)

Webhook header authentication

Header-based authentication lets UiPath validate every incoming webhook request against a shared secret you configured at connection creation. This prevents unauthorized callers from triggering your workflows by posting to your webhook URL.

工作方式

When header-based authentication is enabled on a connection, Integration Service:

1. Checks every incoming request for the configured header key.
2. Accepts the event if the header is present and its value matches the stored secret.
3. Returns HTTP 401 Unauthorized and does not trigger any workflow if the header is absent or its value does not match.

Example request that UiPath accepts:

POST /webhook HTTP/1.1
Host: <your-uipath-webhook-url>
X-API-Key: a1b2c3d4e5f6789...
Content-Type: application/json

{ "event": "..." }

Example request that UiPath rejects (header missing or value wrong):

HTTP/1.1 401 Unauthorized

配置字段

The following table describes the fields that enable you to configure webhook header authentication on the connection creation screen.

字段	描述	示例
身份验证类型	Enables or disables header validation for this connection.	Header Based Authentication / None
Header Key	Name of the HTTP header the vendor sends.	X-API-Key, X-API-Secret
Header Value	Secret value the vendor sends in that header. Masked at rest.	a1b2c3d4e5f6789...

Vendor compatibility

Header-based authentication only works with vendors that let you configure a custom HTTP header on outbound webhook deliveries.

If you're unsure whether your vendor supports outbound custom headers, check the vendor's webhook documentation.

Updating or rotating the secret

When you edit the connection and change the header value, the new value takes effect immediately for all triggers using that connection. The vendor's configuration must be updated with the new value at the same time, or the vendor's deliveries will fail with HTTP 401 until you do.

Behavior when authentication fails

A request is rejected with HTTP 401 Unauthorized if:

• The expected header is absent from the request.
• The header is present but its value does not match the stored secret.

Failed requests are not retried by UiPath, and no trigger event is dispatched. The vendor's own retry behavior (if any) applies.

Authentication failure traces can be viewed in the Traces section. To help protect our systems from DoS attacks, authentication failure traces are limited to 5 per hour.

重要提示

• Header-based authentication is connection-scoped. All triggers created against the same connection share the same header key and value — updating the connection's secret affects every trigger using it.
• Header-based authentication is independent of challenge verification. Either, both, or neither can be enabled on a connection.
• The header value is stored encrypted and should be handled with the same care as any other credential.
• Header names are case-insensitive per the HTTP specification (X-API-Key and x-api-key are equivalent).