跳转到主要内容

Webhook

Markdown

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

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

信息

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

您系统中会发生什么变化: 现在它会在每次状态变化时收到通知,而不需要轮询 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 按钮

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

步骤 2 — 输入您 API 的 URL​

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

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

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

端点字段,带有 HTTPS 要求的辅助说明文字

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

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

在"认证(Authentication)"下,选择认证类型(Authentication type)。共有五个选项,每个选项要求填写不同的字段:

类型显示的字段使用场景
None(无)无您的 API 不需要认证。仅当它有其他形式的保护时才使用此选项——在没有认证的情况下,任何发现该 URL 的人都可以向其发送数据
API KeySecret(密钥)您的 API 验证一个固定密钥
Basic AuthSecret(密钥)您的 API 使用用户名和密码,采用 HTTP Basic 方式
OAuth 2.0Auth URL、Client ID、Secret您的 API 需要令牌。IDCloud 会从该 URL 获取令牌,并自行完成续期
mTLS客户端证书、私钥、服务器 CA(可选)您的 API 只接受出示证书的客户端发起的调用(双向 TLS)。IDCloud 会在每次通知时出示您提供的证书

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

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

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

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

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

配置 mTLS​

使用 mTLS 时,IDCloud 通过出示客户端证书(双向 TLS)向您的 API 表明身份,而不是发送密钥、密码或令牌。 您的 API 必须配置为要求提供该证书,并信任该证书的颁发者。选择 mTLS 后会显示三个字段:

字段需要提供的内容
客户端证书(PEM)PEM 格式的证书链,叶子证书在前。请在您的证书之后添加中间证书,以便您的 API 能将该证书关联到其信任的颁发机构
私钥(PEM)与证书配对的私钥,PEM 格式且不带密码。它以加密方式存储,不会再次显示
服务器 CA(PEM,可选)仅当您 API 自身的证书由私有证书颁发机构签发时才需要。若不填写,IDCloud 会信任公共证书颁发机构

您可以选择一个 .pem 文件,或粘贴文本。每个字段最多可输入 20,000 个字符。

选择 mTLS 之前,需要了解以下规则:

  • URL 必须是 HTTPS,并且您的 API 必须接受 TLS 1.2 或更高版本。
  • 一旦保存,类型即被锁定。 在此屏幕上,认证类型无法更改为其他类型。要切换方式,请联系 Unico 支持团队。
  • 不发送任何其他凭据。 mTLS 不能与 API Key、Basic Auth 或 OAuth 2.0 在同一个 Webhook 上组合使用。
  • 重定向会被视为失败。 IDCloud 不会跟随重定向,因此请将 URL 指向最终地址。

步骤 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。使用 mTLS 时,则改为验证证书和私钥: 两者都必须是 PEM 格式,私钥不能带密码且必须与证书匹配,证书必须处于有效期内。

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

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

常见问题​

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

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

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

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

如何在 mTLS 证书到期之前更换证书? 编辑 Webhook。证书和私钥会以掩码形式显示。请提供新证书和新私钥—— 即使只有其中一个发生了变化,两者也都是必填项——如果您使用服务器 CA,也请再次提供。然后保存。 IDCloud 会在大约 5 分钟内开始使用新证书,因此请让之前的证书保持有效的时间比这再长一点,然后再吊销。 如果这三个字段保持不变,则继续使用当前的证书。

我可以从 mTLS 切换到其他认证类型吗? 在此屏幕上不可以:保存后,类型会被锁定。 请联系 Unico 支持团队移除 Webhook 配置,然后使用新的方式重新创建。

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

我保存了,但通知没有到达。 请按以下顺序检查:URL 是否正确且为 HTTPS;您的 API 是否处于可用状态; 认证方式是否与其所期望的一致;以及密钥是否输入正确。使用 mTLS 时,还需检查:您的 API 是否信任证书的颁发者; 证书是否已过期;以及当您 API 的证书来自私有证书颁发机构时,是否已填写服务器 CA。 认证失败不会在此屏幕上显示为错误——它们发生在投递(delivery)的那一刻。

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

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

快速参考​

IDCloud Portal
└─ 设置(侧边栏中的齿轮图标)
└─ Webhook 选项卡
├─ 客户端信息 ....... 客户端 URL(端点),HTTPS
├─ 认证 ............ None(无) | API Key | Basic Auth | OAuth 2.0 | mTLS
│ OAuth 2.0:+ Auth URL 和 Client ID
│ mTLS:+ 客户端证书、私钥、服务器 CA(可选)
└─ 重试(可选) ....... 最大重试次数
速率限制(req/s)
最小时间(2 秒) · 最大时间(10 秒)
最大持续时间(2 秒) · 最大加倍次数(5)

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