UiPath Documentation
integration-service
latest
false
Integration Service 用户指南
重要 :
请注意，此内容已使用机器翻译进行了本地化。 Integration Service 中提供的连接器包采用的是机器翻译的译文。 新发布内容的本地化可能需要 1-2 周的时间才能完成。

HTTP Webhook 身份验证

将 UiPath 连接到您的 Webhook 提供程序，并配置 Webhook 质询验证或基于标头的身份验证。

先决条件​

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

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

创建 HTTP Webhook 连接​

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

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

  3. 选择“添加连接”。

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

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

  6. （可选）配置基于标头的身份验证。

    如果您希望 UiPath 验证每个传入的 Webhook 请求，请从“身份验证类型”下拉列表中选择“基于标头的身份验证” ，然后指定：

    • 标头密钥— 供应商用于发送凭据的 HTTP 标头（例如X-API-Key或X-API-Secret ）。
    • 标头值— 供应商在该标头中发送的密码值（例如a1b2c3d4e5f6789... ）。此字段已掩码并安全存储。您也可以对此字段使用凭据资产。

    在供应商的 Webhook 设置中配置相同的标头键和值。如果值在运行时不匹配，则 UiPath 将通过 HTTP 401 拒绝请求。

    有关更多信息，请参阅Webhook 标头身份验证。

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

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

  8. 配置质询验证并连接
    如果供应商需要握手，请输入与供应商模式匹配的质询验证（要读取哪个字段/标头/查询以及如何回显/验证）。配置完成后，选择“连接” 。

    在可用的情况下，选择字段旁边的菜单，然后选择“使用凭据资产”或“使用 Orchestrator 资产”以引用 Orchestrator 资产，而不是直接输入值。有关更多信息，请参阅使用凭据资产进行连接。

提示：
  • 使用包含供应商和环境的名称（例如 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": "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
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 标头身份验证​

基于标头的身份验证可让 UiPath 根据您在创建连接时配置的共享密码验证每个传入的 Webhook 请求。这样可以防止未经授权的调用者通过发布到您的 Webhook URL 来触发您的工作流。

工作方式​

在连接上启用基于标头的身份验证时，Integration Service：

  1. 检查每个传入请求中是否存在已配置的标头键。
  2. 如果标头存在并且其值与存储的密码匹配，则接受事件。
  3. 如果标头不存在或其值不匹配，则返回HTTP 401 Unauthorized ，并且不触发任何工作流。

Webhook 标头身份验证

UiPath 接受的请求示例：

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

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

{ "event": "..." }

UiPath 拒绝的示例请求（标头缺失或值错误）：

HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

配置字段​

下表介绍了用于在连接创建屏幕上配置 Webhook 标头身份验证的字段。

字段描述示例
身份验证类型为此连接启用或禁用标头验证。Header Based Authentication / None
标头密钥供应商发送的 HTTP 标头的名称。X-API-Key, X-API-Secret
标头值供应商在该标头中发送的密码值。在静态时掩码。a1b2c3d4e5f6789...

供应商兼容性​

基于标头的身份验证仅适用于允许您在出站 Webhook 交付上配置自定义 HTTP 标头的供应商。

如果您不确定供应商是否支持出站自定义标头，请查看供应商的 Webhook 文档。

更新或轮换密码​

当您编辑连接并更改标头值时，新值立即对使用该连接的所有触发器生效。在您这样做之前，必须同时使用新值更新供应商的配置，否则供应商的交付将失败，并显示 HTTP 401。

身份验证失败时的行为​

如果出现以下情况，请求将被拒绝，并显示“HTTP 401 Unauthorized” ：

  • 请求中缺少预期标头。
  • 标头存在，但其值与存储的密码不匹配。

UiPath 不会重试失败的请求，也不会调度任何触发器事件。供应商自己的重试行为（如果有）适用。

可以在“追踪”部分中查看身份验证失败追踪。为了帮助保护我们的系统免受 DoS 攻击，将身份验证失败追踪限制为每小时 5 个。

重要提示​

  • 基于标头的身份验证在连接作用域内。针对同一连接创建的所有触发器共享相同的标头键和值——更新连接密码会影响使用该密码的每个触发器。
  • 基于标头的身份验证独立于质询验证。可以在连接上同时启用其中一项，也可以都不启用。
  • 标头值加密存储，应像处理任何其他凭据一样谨慎处理。
  • 根据 HTTP 规范，标头名称不区分大小写（ X-API-Key和x-api-key等效）。

此页面有帮助吗？

连接

需要帮助? 支持

想要了解详细内容？ UiPath Academy

有问题? UiPath 论坛

保持更新