Webhook Data Objects

This document defines the data structures for webhook events. Each event type has its own data carrier structure, and all data is contained within the data object field. All webhook events support idempotency through the X-Webhook-Trace-ID header field.

Common Fields

All webhook events include these common fields:

Field	Type	Description
`event_type`	string	The type of event (e.g., `payment.created`, `payment.completed`)
`event_id`	string	Unique identifier for this event
`timestamp`	string	ISO 8601 timestamp when the event occurred
`data`	object	Event-specific data payload

1. Payment Events

{
  "event_type": "payment.created",
  "event_id": "evt_1234567890abcdef",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "payment_id": "pay_1234567890abcdef",
    "amount": "100.00",
    "currency": "USD",
    "status": "pending",
    "payment_method": "crypto",
    "crypto_currency": "USDT",
    "exchange_rate": "1.0000",
    "fiat_amount": "100.00",
    "crypto_amount": "100.00",
    "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}

2. Exchange Rate Events

{
  "event_type": "exchange_rate.updated",
  "event_id": "evt_1234567890abcdef",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "base_currency": "USD",
    "quote_currency": "USDT",
    "rate": "1.0000",
  }
}

3. KYC Events

{
  "event_type": "kyc.verification_started",
  "event_id": "evt_1234567890abcdef",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "kyc_id": "kyc_1234567890abcdef",
    "customer_id": "cust_1234567890abcdef",
    "verification_type": "individual",
    "status": "pending",
    "started_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "customer_email": "[email protected]",
      "customer_name": "John Doe"
    }
  }
}

Idempotency

All webhook events support idempotency through the X-Webhook-Trace-ID header field. This ensures that:

Duplicate Prevention: The same event won't be processed multiple times
Retry Safety: Failed webhook deliveries can be safely retried
Consistency: Event processing is consistent across multiple deliveries

Idempotency Header

The X-Webhook-Trace-ID header is provided by QuickPay and contains a unique trace ID for each webhook event. Merchants should use this trace ID to implement their own idempotency handling.

Idempotency Handling

When processing webhooks:

Check for existing processing: Look up the X-Webhook-Trace-ID value in your database
If not processed: Process the event and store the trace ID
If already processed: Return success without reprocessing
Store for 24 hours: Keep trace IDs for at least 24 hours