---
title: Webhook
description: 配置 IDCloud 在验证流程状态变化时通知您系统的位置、它如何针对您的 API 进行认证，以及当您的 API 无响应时会发生什么。
canonical: https://developer.unico.io/zh-CN/dual-api/product-guide/portal-idcloud/settings/webhook
locale: zh-CN
generated_by: markdown-export
---

**Webhook** 是 IDCloud 在身份验证流程中发生某些事情时自动通知您系统的方式。您的系统不再需要询问"完成了吗？"，
IDCloud 会在事件发生的那一刻调用您的 API。

在此屏幕上，您可以设置您 API 的地址、IDCloud 如何针对它进行认证，以及当它无响应时会发生什么。

:::info
**适用对象：** 希望自动接收流程结果、而不进行轮询的客户。适用于所有集成类型。

**您系统中会发生什么变化：** 现在它会在每次状态变化时收到通知，而不需要轮询 IDCloud。

**在哪里找到它：** IDCloud Portal → 侧边栏 **设置（Settings）** → **Webhook** 选项卡。
:::

## 开始之前

### 访问权限

您的用户需要具有 **Configurator（配置员）** 权限档案——与授予 Journey Customization 访问权限的档案相同。
如果 Webhook 选项卡没有显示出来，请联系您的账户管理员。

### 配置如何生效

| | |
| :- | :- |
| **范围** | 每个**租户和分支（tenant and branch）**一个 Webhook。没有列表：如果已经配置了一个，会对其进行编辑，而不是重复创建。 |
| **独立的环境** | Staging Portal 配置的是 UAT 的 Webhook；Production 则配置 Production 的。配置其中一个不会影响另一个。 |
| **何时生效** | 保存后立即生效。 |
| **密钥安全性** | 密钥经过加密，且不会再以明文显示。屏幕上始终以掩码形式显示。 |

### 需要提前准备的内容

- 用于接收通知的 API 的 **HTTPS URL**。在保存之前，它需要处于可用状态并能够接受请求。
- 您 API 所期望的**凭据**，具体取决于您选择的认证方式（见步骤 3）。
- 如果您的 API 有容量限制，需要知道它支持的**每秒请求数**。

### 需要提前决定的事项

有两项技术决定取决于维护您 API 的人，而不是操作 Portal 的人。在打开此屏幕之前，值得先对齐：

- 您的 API 要求使用**哪种认证方式**。
- 是否需要**调整重试策略**，还是保留默认设置。默认设置适用于大多数情况。

## 分步操作

### 步骤 1 — 打开 Webhook 选项卡

在 IDCloud Portal 中，点击侧边栏中的**齿轮图标（设置）**，然后选择 **Webhook** 选项卡。

如果您还没有配置 Webhook，屏幕会显示**"尚未创建 Webhook"**以及一个**创建 Webhook**按钮。如果已经配置了一个，
屏幕会显示**您的 Webhook**卡片，其中包含端点、认证类型和掩码后的密钥，以及一个用于编辑它的**配置 Webhook**按钮。

![管理您的 Webhook 卡片，带有配置 Webhook 按钮](/img/product-guide/webhook/en/01-manage-webhook.png)

*"您的 Webhook" 卡片，包含端点、认证类型和掩码后的密钥。*

### 步骤 2 — 输入您 API 的 URL

点击**创建 Webhook**（如果已存在则点击**配置 Webhook**），并在"客户端信息"下填写
**客户端 URL（端点）（Client URL (Endpoint)）**字段。

这是 IDCloud 将发送通知的地址。它必须是 **HTTPS**。

**将其指向一个已经处于可用状态的地址。** IDCloud 会在您保存后立即开始调用此 URL。如果它还不存在，
最初的几次通知会失败，并在您的团队注意到之前耗尽重试次数。

![端点字段，带有 HTTPS 要求的辅助说明文字](/img/product-guide/webhook/en/02-edit-webhook.png)

*端点字段，带有关于 HTTPS 要求的辅助说明文字。*

### 步骤 3 — 选择 IDCloud 如何针对您的 API 进行认证

在"认证（Authentication）"下，选择**认证类型（Authentication type）**。共有四个选项，每个选项要求填写不同的字段：

| 类型 | 显示的字段 | 使用场景 |
| :- | :- | :- |
| **None（无）** | 无 | 您的 API 不需要认证。仅当它有其他形式的保护时才使用此选项——在没有认证的情况下，任何发现该 URL 的人都可以向其发送数据 |
| **API Key** | Secret（密钥） | 您的 API 验证一个固定密钥 |
| **Basic Auth** | Secret（密钥） | 您的 API 使用用户名和密码，采用 HTTP Basic 方式 |
| **OAuth 2.0** | Auth URL、Client ID、Secret | 您的 API 需要令牌。IDCloud 会从该 URL 获取令牌，并自行完成续期 |

对于 **OAuth 2.0**，**Auth URL** 是 IDCloud 获取令牌的地址——它不是接收通知的 URL。这是两个不同的地址，
在此屏幕上互换它们是最常见的错误。

**Secret（密钥）**以加密方式存储。编辑现有 Webhook 时，该字段显示为空：填写它会覆盖当前的密钥，
留空则保留已有的值。

**在保存之前，请与维护您 API 的人确认该认证方式。** 错误的认证方式不会在屏幕上产生错误提示——它会导致
通知在之后悄无声息地失败，只有当结果没有到达时您才会发现。

![认证类型字段以及与之对应的凭据字段](/img/product-guide/webhook/en/02-edit-webhook.png)

*认证类型字段以及与之对应的凭据字段。*

### 步骤 4 — 如有需要，调整重试策略

**重试配置（Retry configuration）**部分是**可选**的，默认处于关闭状态。仅在需要更改默认行为时才开启它。

开启后会显示六个字段：

| 字段 | 控制的内容 | 默认值 |
| :- | :- | :- |
| **最大重试次数（Maximum retries）** | IDCloud 在放弃之前再次尝试的次数 | — |
| **速率限制（Rate limit，req/s）** | 每秒最大通知数。如果您的 API 容量有限，可降低该值 | — |
| **最小时间（Minimum time，秒）** | 两次尝试之间的最小间隔 | 2 秒 |
| **最大时间（Maximum time，秒）** | 两次尝试之间的最大间隔 | 10 秒 |
| **最大持续时间（Maximum duration，秒）** | 在判定单次尝试失败之前等待的时长 | 2 秒 |
| **最大加倍次数（Maximum doublings）** | 尝试间隔的增长系数（backoff） | 5 |

综合行为是：IDCloud 尝试一次，等待**最小时间**，再次尝试，并按照**最大加倍次数**不断增加间隔，
直到达到**最大时间**——如此重复，直到达到**最大重试次数**。每次单独的尝试都会在**最大持续时间**之后放弃。

**先调整速率限制，再改动其他任何设置。** 如果您的 API 在负载下崩溃，问题在于吞吐量，而不是重试次数——
在这种情况下增加重试次数只会让情况变得更糟，因为它会使调用次数成倍增加。请先降低速率。

**增加最大重试次数并不能替代一个稳定的 API。** 重试用于应对短暂的不可用状态。如果您的 API 频繁失败，
此设置只会延迟您丢失通知的时刻。

![切换开关打开后显示的六个重试字段](/img/product-guide/webhook/en/02-edit-webhook.png)

*切换开关打开后显示的六个重试字段。*

### 步骤 5 — 保存

点击**保存（Save）**。**取消（Cancel）**会放弃所有更改并保留之前的配置。

当认证方式为 OAuth 2.0 时，IDCloud 会在允许保存之前验证令牌 URL。

保存后，**您的 Webhook** 卡片会显示端点和认证类型。密钥会以掩码形式显示，且无法再从屏幕上取回——
如果您丢失了该值，需要设置一个新的值。

**在认为完成之前，请进行一次真实测试。** 在 Staging 中启动一个流程，并确认通知已到达您的 API。
该屏幕只能确认配置已保存，并不能确认您的 API 已经收到通知。

## 常见问题

**我可以注册多个 Webhook 吗？** 不可以。每个租户和分支只能有一个 Webhook。如果已经存在一个，
它会被编辑——无法创建第二个。

**我在 Staging 中配置了它。它也适用于 Production 吗？** 不适用。两个环境是独立的：Staging Portal
配置的是 UAT 的 Webhook，Production 则配置 Production 的。您需要在 Production Portal 中重复该配置。

**如何查看我注册的密钥？** 无法查看。它在保存时被加密，并始终以掩码形式显示。如果您丢失了该值，
请通过 Secret 字段注册一个新值——填写它会覆盖之前的值。

**我编辑了 Webhook，但不想更改密钥。该怎么做？** 将 Secret 字段留空即可。当前的值会被保留。

**如何删除 Webhook？** 该屏幕不提供删除功能。要移除配置，请联系 Unico 支持团队。如果目的只是停止接收
通知或更改目标地址，请改为编辑 URL。

**我保存了，但通知没有到达。** 请按以下顺序检查：URL 是否正确且为 HTTPS；您的 API 是否处于可用状态；
认证方式是否与其所期望的一致；以及密钥是否输入正确。认证失败不会在此屏幕上显示为错误——它们发生在
投递（delivery）的那一刻。

**"最大持续时间（Maximum duration）"和"最大时间（Maximum time）"有什么区别？** "最大时间"是两次尝试**之间**
的最长间隔。"最大持续时间"是 IDCloud 在判定**单次**尝试失败之前等待的时长。

**如果我已经通过 API 轮询结果，还需要 Webhook 吗？** 并非必须，但它可以让您的系统免于轮询。如果您已经有
一个可正常工作的轮询机制，Webhook 只是一种优化，而不是必需项。

## 快速参考

```text
IDCloud Portal
 └─ 设置（侧边栏中的齿轮图标）
     └─ Webhook 选项卡
         ├─ 客户端信息 ....... 客户端 URL（端点），HTTPS
         ├─ 认证 ............ None（无） | API Key | Basic Auth | OAuth 2.0
         │                    OAuth 2.0：+ Auth URL 和 Client ID
         └─ 重试（可选） ....... 最大重试次数
                                速率限制（req/s）
                                最小时间（2 秒） · 最大时间（10 秒）
                                最大持续时间（2 秒） · 最大加倍次数（5）

每个租户和分支一个 Webhook · UAT 和 Production 相互独立 · 密钥永不显示 · 取消 · 保存
```