> ## 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 介绍

Webhook 是 Cobo 支付服务与您的 App 进行通信的重要机制。在您设置并注册 Webhook Endpoint 后，当事件发生时，Cobo 支付服务会将推送消息发送到指定的 URL。它们允许您的 App 实时接收更新或通知，并相应地响应事件。

您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看您团队中所有 Webhook 事件的数据。

## 处理 Webhook 事件

按照以下步骤处理 Cobo 支付服务发送的 Webhook 事件：

1. 创建一个 Webhook Endpoint。
   * 选择服务器环境。
   * 定义 Endpoint URL。
2. 在服务器端实现处理逻辑。
   * 解析 API 请求。
   * 验证签名。
   * 响应 API 请求。
   * 添加其他处理逻辑（如果适用）。
3. 在 Cobo Portal 上注册 Endpoint。
   <Note>注册 Webhook Endpoint 时，您需要指定要订阅的事件类型。</Note>

要创建 Endpoint 并实现处理逻辑，请参阅 [设置 Webhook Endpoint](/payments/cn/developer-tools/set-up-endpoint)。

要注册 Endpoint，请参阅 [注册 Webhook Endpoint](https://manuals.cobo.com/cn/portal/developer-console/webhooks-create)。

要了解事件类型和事件数据类型的信息，请参阅[事件与状态](/payments/cn/guides/status-and-events)。

## Webhook 请求体

当事件触发时，Cobo 支付服务会向您注册的 Endpoint 发送 HTTP POST 请求。请求体为 JSON 对象，结构如下。

### 必填字段

| 字段                  | 类型              | 说明                                                                                 |
| :------------------ | :-------------- | :--------------------------------------------------------------------------------- |
| `event_id`          | string (UUID)   | 事件唯一标识符。使用 `event_id` 对重试推送进行去重。                                                   |
| `url`               | string          | 已注册的 Webhook Endpoint URL。                                                         |
| `created_timestamp` | integer (int64) | 事件触发时间，Unix 时间戳格式（毫秒）。重试时该值保持不变。                                                   |
| `type`              | string          | 事件类型。所有事件类型及触发条件请参阅[事件与状态](/payments/cn/guides/status-and-events)。                 |
| `data`              | object          | 事件专属负载。结构取决于 `type` 字段——各事件的字段结构请参阅[事件与状态](/payments/cn/guides/status-and-events)。 |

### 选填字段

| 字段                     | 类型              | 说明                                                     |
| :--------------------- | :-------------- | :----------------------------------------------------- |
| `status`               | string          | 事件推送状态，可能的值：`Success`、`Retrying`、`Failed`。             |
| `next_retry_timestamp` | integer (int64) | 下次重试的计划时间，Unix 时间戳格式（毫秒）。仅在 `status` 为 `Retrying` 时存在。 |
| `retries_left`         | integer         | 剩余重试次数。仅在 `status` 为 `Retrying` 时存在。                   |

### 请求体示例

```json theme={null}
{
  "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f",
  "url": "https://example.com/webhook",
  "created_timestamp": 1701396866000,
  "type": "payment.order.status.updated",
  "data": {
    "data_type": "PaymentOrder",
    "order_id": "O20250304-M1001-1001",
    "merchant_id": "1001",
    "psp_order_code": "P20240201001",
    "pricing_currency": "USD",
    "pricing_amount": "100.00",
    "fee_amount": "2.00",
    "payable_currency": "ETH_USDT",
    "chain_id": "ETH",
    "payable_amount": "103.03",
    "exchange_rate": "0.99",
    "receive_address": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "Completed",
    "received_token_amount": "103.0305",
    "created_timestamp": 1744689600,
    "updated_timestamp": 1744689600
  },
  "status": "Success"
}
```