跳转到主要内容

Webhook

MarkdownChatGPTClaude

本文档中的 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：用户未在规定时间内完成捕获，交易已过期。
关于身份验证

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

与无卡验证的集成​

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

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

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

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

请求​

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

{
  "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 参考 部分中有说明。

最后更新 于