Skip to main content
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.
    When registering a webhook endpoint, you need to specify the event types to which you want to subscribe.
To create an endpoint and implement the handling logic, see Set up a webhook endpoint. To register the endpoint, see Register a webhook endpoint. To learn more about event types and event data types, see Events and status.

​
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

FieldTypeDescription
event_idstring (UUID)The unique identifier of the event. Use event_id to deduplicate retried deliveries.
urlstringThe registered webhook endpoint URL.
created_timestampinteger (int64)The time when the event was triggered, in Unix timestamp format (milliseconds). This value remains unchanged across retries.
typestringThe event type. See Events and status for all event types and their trigger conditions.
dataobjectThe event-specific payload. The schema depends on the type field — see Events and status for per-event schemas.

​
Optional fields

FieldTypeDescription
statusstringThe delivery status of the event. One of: Success, Retrying, Failed.
next_retry_timestampinteger (int64)The scheduled time of the next retry attempt, in Unix timestamp format (milliseconds). Only present when status is Retrying.
retries_leftintegerThe number of retry attempts remaining. Only present when status is Retrying.

​
Example request body

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