> ## 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.

# Introduction to Webhooks

Webhooks are essential mechanisms for the Cobo payments service to communicate with your application. After you set up and register webhook endpoints, the Cobo payments service sends push messages to the designated URL when an event occurs. They allow your application to receive real-time updates or notifications and to respond to events accordingly.

You can view the data of all webhook events in your organization on **Cobo Portal** > **Developer** > **Webhook Events**.

## Handle webhook events

Follow the steps listed below to handle webhook events sent from the Cobo payments service:

1. Create a webhook endpoint.
   * Choose a server environment.
   * Define an endpoint URL.
2. Implement the handling logic on the server side.
   * Parse the API request.
   * Verify the signature.
   * Respond to the API request.
   * Add other handling logic (if applicable).
3. Register the endpoint on Cobo Portal.
   <Note>When registering a webhook endpoint, you need to specify the event types to which you want to subscribe.</Note>

To create an endpoint and implement the handling logic, see [Set up a webhook endpoint](/payments/en/developer-tools/set-up-endpoint).

To register the endpoint, see [Register a webhook endpoint](https://manuals.cobo.com/en/portal/developer-console/webhooks-create).

To learn more about event types and event data types, see [Events and status](/payments/en/guides/status-and-events).

## Webhook request body

When an event is triggered, the Cobo payments service sends an HTTP POST request to your registered endpoint. The request body is a JSON object with the following structure.

### Required fields

| Field               | Type            | Description                                                                                                                                                |
| :------------------ | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id`          | string (UUID)   | The unique identifier of the event. Use `event_id` to deduplicate retried deliveries.                                                                      |
| `url`               | string          | The registered webhook endpoint URL.                                                                                                                       |
| `created_timestamp` | integer (int64) | The time when the event was triggered, in Unix timestamp format (milliseconds). This value remains unchanged across retries.                               |
| `type`              | string          | The event type. See [Events and status](/payments/en/guides/status-and-events) for all event types and their trigger conditions.                           |
| `data`              | object          | The event-specific payload. The schema depends on the `type` field — see [Events and status](/payments/en/guides/status-and-events) for per-event schemas. |

### Optional fields

| Field                  | Type            | Description                                                                                                                      |
| :--------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `status`               | string          | The delivery status of the event. One of: `Success`, `Retrying`, `Failed`.                                                       |
| `next_retry_timestamp` | integer (int64) | The scheduled time of the next retry attempt, in Unix timestamp format (milliseconds). Only present when `status` is `Retrying`. |
| `retries_left`         | integer         | The number of retry attempts remaining. Only present when `status` is `Retrying`.                                                |

### Example request body

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