跳转到主要内容

配置

要在 Unico IDCloud 上配置 Webhook，请提供您的端点、认证方式和重试策略。配置由 Unico 团队完成——请联系您的 CS / Onboarding 团队以注册或更新 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": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

有关完整载荷结构和 lastEvent 值列表，请参阅事件类型。

预期响应​

您的端点必须同步响应：

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

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

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

最后更新 于