> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置 Webhook Endpoint

Webhook 事件对于确保 Cobo 支付服务与您的 App 之间的无缝数据集成和通信至关重要。本指南介绍如何搭建一个用于接收和处理 Webhook 事件的 Endpoint。

## 创建 Endpoint

首先，选择一个支持接收和处理 Webhook 事件的服务器环境，例如 AWS、Google Cloud 或自托管服务器。然后，在您的服务器上定义一个 Endpoint URL，以便接收 Webhook 事件。

## 实现处理逻辑

创建 Endpoint 后，您需要在服务器上实现逻辑以处理 Webhook 事件，包括解析 API 请求、验证签名、响应请求以及在必要时添加其他处理逻辑。

### 验证签名

为了防止未经授权的访问，当您收到 Webhook 事件时，您需要通过验证签名来验证 API 请求的真实性。

验证步骤如下：

1. 获取请求包体的原始数据和时间戳。

   从请求 Payload 中提取包体的原始字符串，并从请求头中提取时间戳。

   ```python theme={null}
   raw_body = request.body().decode('utf8')
   timestamp = request.headers.get("BIZ_TIMESTAMP")
   ```

2. 获取签名。

   从请求头中获取签名值。

   ```python theme={null}
   signature = request.headers.get('BIZ_RESP_SIGNATURE')
   ```

3. 拼接消息并对其进行哈希处理。

   ```python theme={null}
   import hashlib

   # Concatenate raw body and timestamp to form the message.
   message = "raw_body|timestamp"

   # Compute double SHA-256 hash.
   sha256_hash = hashlib.sha256(hashlib.sha256(message.encode()).digest()).digest()
   ```

4. 选择 Cobo 的公钥。

   根据您使用的环境，选择相应的公钥进行验证：

   * 开发环境：`a04ea1d5fa8da71f1dcfccf972b9c4eba0a2d8aba1f6da26f49977b08a0d2718`
   * 生产环境：`8d4a482641adb2a34b726f05827dba9a9653e5857469b8749052bf4458a86729`

5. 使用 Ed25519 算法验证签名。

   ```python theme={null}
   import ed25519

   # Obtain the verifying key from Cobo's public key.
   vk = ed25519.VerifyingKey(bytes.fromhex(public_key)) 

   # Verify the signature against the computed message hash.
   vk.verify(bytes.fromhex(signature), sha256_hash)
   ```

### 响应 API 请求

当您的 Webhook Endpoint 收到 Webhook 事件时，它应该响应状态码 `200` 或 `201` 以指示事件已成功接收和处理。一旦发送此响应，Cobo 支付服务将停止重试发送事件，事件状态将变为**已送达**。

默认情况下，每个 Webhook 事件的超时时间为 2 秒。如果 Webhook Endpoint 没有响应或响应状态码不是 `200` 或 `201`，Cobo 支付服务将继续重试发送事件。如果重试次数达到 10 次，Cobo 支付服务将停止发送事件，事件状态将变为**发送失败**。您可以通过单击 Cobo Portal > 开发者 > Webhook 事件上的**重新发送**来重新发送事件。

Cobo 不保证事件将按生成顺序交付。例如，创建转账将生成以下事件：

* `wallets.transaction.created`
* `wallets.transaction.updated`
* `wallets.transaction.succeeded`

您的 Endpoint 不应假设事件将按此顺序到达。

### 代码示例

要查看如何实现处理逻辑的示例，请参阅 GitHub 库中的如下文件：

* Python：[server\_demo.py](https://github.com/CoboGlobal/cobo-waas2-python-sdk/blob/master/cobo_waas2/server_demo.py)（基于 FastAPI 框架实现）
* Java：[DemoController.java](https://github.com/CoboGlobal/cobo-waas2-java-sdk/blob/master/src/main/java/com/cobo/waas2/demo/DemoController.java)（基于 SpringBoot 框架实现）
* JavaScript：[ServerDemo.js](https://github.com/CoboGlobal/cobo-waas2-js-sdk/blob/master/src/ServerDemo.js)
* Go：[server\_demo.go](https://github.com/CoboGlobal/cobo-waas2-go-sdk/blob/master/cobo_waas2/demo/server_demo.go)

## ⚠️⚠️⚠️ 注意事项

<Warning>
  * 在接收 Webhook 事件时，您的 Endpoint 应该首先快速返回正确的状态码，然后异步处理任何后续处理，以防止超时。
  * 由于 Webhook 事件存在重试机制，Webhook Endpoint 有时会多次接收到相同的事件。为了防止重复事件处理，请记录已处理的 Event ID，Transaction Hash 或 Transaction ID，并避免处理已记录的事件。
</Warning>