Webhook 介绍 - Cobo Payments

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

处理 Webhook 事件

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

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

要创建 Endpoint 并实现处理逻辑，请参阅设置 Webhook Endpoint。要注册 Endpoint，请参阅注册 Webhook Endpoint。要了解事件类型和事件数据类型的信息，请参阅事件与状态。

Webhook 请求体

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

必填字段

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

选填字段

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

请求体示例

{
  "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"
}