--- title: 配置 description: IDCloud Webhook 配置分步指南 — 通过门户为 Web 和 SDK 进行自助配置，以及通过客户端为使用 Check 编排的 API 集成进行配置（仅限巴西）。 canonical: https://developer.unico.io/zh-CN/dual-api/developers/webhooks-and-events/setup locale: zh-CN generated_by: markdown-export --- IDCloud 支持两种 Webhook 模式，具体取决于您的集成方式： - **通过门户** — 适用于 Web 和 SDK 集成。直接在 IDCloud 门户中进行自助配置。 - **按客户端** — 适用于使用 **Check 编排**能力（异步流程）的 API 集成。由 Unico 团队配置。**仅限巴西**。 ### 通过门户（Web 和 SDK） 要注册或更新您的 Webhook 端点，请访问 IDCloud 门户并导航至**设置 > Webhook**。 #### 所需信息 | 字段 | 描述 | |---|---| | **通知 URL** | Unico 用于投递事件通知的端点。必须可通过 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 ` 请求头发送。 ****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 `），请使用 `header:value` 格式；仅值格式会直接发送原始值，不附加任何前缀。 ****无认证**** 不发送任何凭据。仅建议用于开发环境——生产环境端点应始终要求认证。 #### 触发通知的流程状态 目前，每当流程转换到以下状态时，Unico 会发送通知： | 状态 | 描述 | |---|---| | `PROCESS_STATE_FINISHED` | 流程已完成——终止状态，与结果无关。 | :::warning[状态可能演进] 平台通知的状态集合在未来可能发生变化。请将您端点响应的状态设为**可配置**，以便新增状态时无需重新部署服务。 ::: #### 请求格式 Webhook 投递是向您端点发送的 **POST** 请求。请求体包含流程标识符和当前状态。 ```json { "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0", "state": "PROCESS_STATE_FINISHED", "flow": "id" } ``` :::note[`lastEvent` 和 `lastEventDescription`] 这两个字段**仅在流程在用户完成旅程之前过期时**出现在载荷中。正常完成的载荷中不包含这两个字段。完整结构及 `lastEvent` 可能值的列表，请参阅[事件类型](/developers/webhooks-and-events/event-types)。 ::: #### 预期响应 您的端点必须**同步**响应： - **成功**：`200`–`299` 范围内的任意 HTTP 状态码。 - **失败**：其他任意状态码。Unico 将以指数退避方式重试，直至达到配置的最大尝试次数，或收到 `2xx` 响应为止。 :::tip[快速响应] 请迅速确认 Webhook（在配置的超时时间内），并在您侧异步处理载荷。在 Webhook 处理器中执行长时间处理会增加超时和不必要重试的概率。 ::: 有关幂等性和重试处理的指导，请参阅[安全](/developers/webhooks-and-events/security)。 ### 按客户端（API — 仅限巴西） :::info[仅限巴西] 按客户端 Webhook 仅适用于巴西境内使用 **Check 编排**能力的 API 集成——这是一种异步流程，流程结果通过 Webhook 投递，而非作为同步 API 响应返回。 ::: 要注册或更新您的端点，请联系您的 **CS / Onboarding** 团队。 #### 所需信息 | 字段 | 描述 | |---|---| | **通知 URL** | 您系统暴露的用于接收状态更新的端点。必须可通过 HTTPS 访问。 | | **认证类型** | Unico 对您端点进行认证的方式。请参阅下方选项。 | | **重试设置** | 最大尝试次数及尝试间隔（采用指数退避）。 | | **并发限制** | 最大同时在途投递数量（上限：**500**）。 | | **超时时间** | 等待端点响应的最长时间，单位为秒。 | #### 认证方式 ****OAuth2**** 提供以下信息： - Webhook `endpoint` - OAuth2 提供方 `URL` - OAuth2 提供方 `ClientId` - OAuth2 提供方 `Secret` Unico 将使用客户端凭据向提供方 URL 请求访问令牌，并以 Bearer token 的形式转发至您的端点。 ****Basic Authorization**** 以 `user:pass` 格式提供凭据。Unico 会将其 Base64 编码后，在每次 Webhook 调用时通过 `Authorization: Basic ` 请求头发送。 ****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 `），请使用 `header:value` 格式；仅值格式会直接发送原始值，不附加任何前缀。 ****无认证**** 不发送任何凭据。仅建议用于开发环境——生产环境端点应始终要求认证。 #### 状态码 按客户端 Webhook 使用**数字状态码**： | 代码 | 描述 | |---|---| | `2` | 差异 — 流程已完成，但身份核验存在差异。 | | `3` | 已完成 — 流程已成功完成。 | | `5` | 错误 — 流程因错误而终止。 | #### 请求格式 Webhook 投递是向您端点发送的 **POST** 请求。请求体包含交易标识符和数字状态码。 ```json { "id": "8263a268-5388-492a-bca2-28e1ff4a69f0", "status": 3 } ``` #### 预期响应 您的端点必须**同步**响应： - **成功**：`200`–`299` 范围内的任意 HTTP 状态码。 - **失败**：其他任意状态码。Unico 将以指数退避方式重试，直至达到配置的最大尝试次数，或收到 `2xx` 响应为止。 :::tip[快速响应] 请迅速确认 Webhook（在配置的超时时间内），并在您侧异步处理载荷。在 Webhook 处理器中执行长时间处理会增加超时和不必要重试的概率。 ::: :::warning[至少一次投递] 平台保证至少一次投递——同一通知可能到达多次。请在您侧使用 `id` 字段实现幂等性，以安全处理重复通知。 有关幂等性和重试处理的指导，请参阅[安全](/developers/webhooks-and-events/security)。 :::