---
title: Webhook
description: 如何配置和接收无卡验证 Webhook 通知，包括请求/响应格式以及速率限制和幂等性等重要注意事项。
canonical: https://developer.unico.io/zh-CN/dual-api/developers/regional-solutions/card-not-present-verification/integration/webhook
locale: zh-CN
generated_by: markdown-export
---

本文档中的 GetProcess 系列文章介绍了一种通过调用端点获取流程状态的方法。通过这种方式，系统会进行轮询（polling）以接收已创建流程的信息。这意味着可以针对同一流程多次调用该端点，以获取最新状态。

通过使用 Webhook，可以在流程状态每次发生变化时通知特定端点。

### 什么是 Webhook？

Webhook 是一种系统性通知服务，可实现系统之间的异步集成，其中一个系统通过触发器通知另一个系统。通过这种方式，Webhook 可以让系统保持最新信息，而无需持续轮询来检查更新。

### 如何配置 Webhook

要配置 Webhook，需要提供以下信息：

- **通知 URL：** 此为 Unico 用于发送状态更新通知的端点。
- **身份验证类型：** 用于对端点调用进行身份验证的方法。可选项如下：
  - OAuth2；
  - 基本身份验证（Basic Authorization）；
  - API 密钥（API Key）；
  - 无身份验证。
- 对于 **OAuth2**，需要提供以下信息：
  - Webhook `endpoint`；
  - OAuth2 提供方的 `URL`；
  - OAuth2 提供方的 `ClientId`；
  - OAuth2 提供方的 `Secret`。
- 对于基本身份验证，需要以 `user:pass` 格式发送。
- 对于 API 密钥，有两种可能的格式：
  - `header:value`，当需要指定特定的请求头名称时；
  - `value`，当所需的请求头为 `Authorization` 时。
- **重试设置：** 表示调用端点失败时的重试次数：
  - 最大尝试次数；
  - 尝试间隔（以秒为单位）；
  - **速率限制（Rate Limit）：** 同时提交的最大数量（最大值：500）；
  - **超时（Timeout）：** 等待端点响应的最长时间（以秒为单位）。
- **需通知的状态：** 您可以订阅特定状态以接收通知，包括：
  - `approved`：交易已批准；
  - `processing`：交易处理中；
  - `inconclusive`：未能完成结论性验证；
  - `shared`：交易已分享，等待提交；
  - `skipped`：用户在流程中跳过了生物识别捕获；
  - `unknown-share`：用户标记为不认识该笔购买；
  - `absent-holder`：持卡人未在场进行捕获；
  - `expired`：用户未在规定时间内完成捕获，交易已过期。

:::note[关于身份验证]
API 可以通过身份验证方法（如基本身份验证或 API 密钥）进行保护。也可以定义有效访问 IP 列表，以提供额外保护。
:::

### 与无卡验证的集成

在平台上配置 Webhook 后，您可以通过发送到您所开发的 API 端点的通知，接收有关流程的信息，以获取这些更新。

平台发送给该 API 的信息包括：

- **ID**：交易 ID；
- **Status**：交易状态；
- **HasIdentityChanged**：交易中是否发生了身份变更（可选）。

:::note
请注意，可以通过 Webhook 配置选择客户希望被通知的状态。发送此信息后，预期的响应应为同步响应。
:::

#### 请求

该请求必须是对 REST API 的 POST 方法调用，这样可以更轻松、更安全地发送信息。所有字段均为必填项。请求体应包含交易 ID 和状态，如以下示例所示：

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}
```

#### 响应

响应应为同步响应。成功请求的状态码应在 200 到 299 之间。其他任何状态码都将被视为失败，无卡验证将进行额外的通知尝试（尝试之间采用指数退避），直到收到 2xx 响应或达到最大尝试次数为止。

#### 响应状态

目前，我们提供一组状态，但该集合未来可能会发生变化。因此，建议将客户希望据以采取行动的状态设置为可配置项。例如，如果希望在每次成功完成捕获时采取行动，目前对应的状态是 "processing"。但由于未来这一状态可能会调整，建议将表示捕获成功的状态设置为系统中的可配置项，以便未来能够轻松切换为 "captured" 状态。

此外，我们建议针对特定状态设置专门的操作，并针对无法识别的状态设置一个通用操作（例如，假设除 "processing" 和 "approved" 之外的所有状态均为未有结论）。这一点非常重要，因为未来可能会出现新的状态，而 Webhook 不应因此而中断。

#### 重要注意事项

在开发供无卡验证用于通知状态变更的 API 时，请注意以下几个方面：

**速率限制（Rate limit）** — 为避免在大量交易的情况下使您的资源过载，可以为端点的调用次数设置上限。

**错误率（Error Rate）** — 错误率（响应状态码不在 [200, 299] 范围内）应始终保持较低水平。否则，Webhook 的吞吐量将被自动降低，而这种降低与重试机制相结合，可能会导致新 Webhook 的执行时间增加。

**幂等性（Idempotence）** — 当前的 Webhook 实现保证至少送达一次（at-least-once），因此同一状态可能会被多次通知。因此，端点的实现应采用幂等方式。

**回退方案（Fallback）** — 如果 Webhook 服务出现任何不可用情况，建议准备一个回退方案，以便您可以在既定的响应时间内继续获取交易状态。该端点查询在本文档的 [API 参考](/developers/regional-solutions/card-not-present-verification/integration/apis/api-reference) 部分中有说明。