Webhook

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

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

信息

适用对象： 希望自动接收流程结果、而不进行轮询的客户。适用于 byUnico 和 byClient 两种集成方式。

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

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

在这个屏幕出现之前，任何 Webhook 变更都需要提交支持工单——仅此一项每月就有约 30 张工单。现在您可以自己 在几分钟内完成，并且在 Staging 和 Production 环境中均可操作。

开始之前

访问权限

您的用户需要具有 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" 卡片，包含端点、认证类型和掩码后的密钥。

步骤 2 — 输入您 API 的 URL

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

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

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

端点字段，带有关于 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 的人确认该认证方式。 错误的认证方式不会在屏幕上产生错误提示——它会导致 通知在之后悄无声息地失败，只有当结果没有到达时您才会发现。

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

步骤 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 频繁失败， 此设置只会延迟您丢失通知的时刻。

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

步骤 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 只是一种优化，而不是必需项。

快速参考

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 相互独立 · 密钥永不显示 · 取消 · 保存