跳转到主要内容

配置

IDCloud 支持两种 Webhook 模式，具体取决于您的集成方式：

  • 通过门户 — 适用于 Web 和 SDK 集成。直接在 IDCloud 门户中进行自助配置。
  • 按客户端 — 适用于使用 Check 编排能力（异步流程）的 API 集成。由 Unico 团队配置。仅限巴西。

要注册或更新您的 Webhook 端点，请访问 IDCloud 门户并导航至设置 > Webhook。

所需信息​

字段描述
通知 URLUnico 用于投递事件通知的端点。必须可通过 HTTPS 访问。
认证类型Unico 对您端点进行认证的方式。请参阅下方选项。
重试设置最大尝试次数及尝试间隔（采用指数退避）。
并发限制最大同时在途投递数量（上限：500）。
超时时间等待端点响应的最长时间，单位为秒。
需通知的状态触发通知的流程状态集合。目前固定为 PROCESS_STATE_FINISHED；暂不支持配置。

认证方式​

OAuth2

提供以下信息：

  • Webhook endpoint
  • OAuth2 提供方 URL
  • OAuth2 提供方 ClientId
  • OAuth2 提供方 Secret

Unico 将使用客户端凭据向提供方 URL 请求访问令牌，并以 Bearer token 的形式转发至您的端点。

Basic Authorization

以 user:pass 格式提供凭据。Unico 会将其 Base64 编码后，在每次 Webhook 调用时通过 Authorization: Basic <encoded> 请求头发送。

API Key

支持两种格式。字符串以第一个冒号为分隔符进行拆分：

  • header:value — 设置自定义请求头名称。示例：
    • X-API-Key:abc123 → X-API-Key: abc123
    • Authorization:Bearer abc123 → Authorization: Bearer abc123
  • 仅 value（不含冒号）— 值将以 Authorization 请求头发送，不带任何方案前缀。示例：abc123 → Authorization: abc123。

当需要 Bearer 方案时（例如 Authorization:Bearer <token>），请使用 header:value 格式；仅值格式会直接发送原始值，不附加任何前缀。

无认证

不发送任何凭据。仅建议用于开发环境——生产环境端点应始终要求认证。

触发通知的流程状态​

目前，每当流程转换到以下状态时，Unico 会发送通知：

状态描述
PROCESS_STATE_FINISHED流程已完成——终止状态，与结果无关。
状态可能演进

平台通知的状态集合在未来可能发生变化。请将您端点响应的状态设为可配置，以便新增状态时无需重新部署服务。

请求格式​

Webhook 投递是向您端点发送的 POST 请求。请求体包含流程标识符和当前状态。

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
lastEvent 和 lastEventDescription

这两个字段仅在 result = expired 时出现在载荷中——即流程在用户完成旅程之前已过期。正常完成的载荷中不包含这两个字段。完整结构及 lastEvent 可能值的列表，请参阅事件类型。

预期响应​

您的端点必须同步响应：

  • 成功：200–299 范围内的任意 HTTP 状态码。
  • 失败：其他任意状态码。Unico 将以指数退避方式重试，直至达到配置的最大尝试次数，或收到 2xx 响应为止。
快速响应

请迅速确认 Webhook（在配置的超时时间内），并在您侧异步处理载荷。在 Webhook 处理器中执行长时间处理会增加超时和不必要重试的概率。

有关幂等性和重试处理的指导，请参阅安全。

最后更新 于