General Payload Structure

6 min

Webhook Payload Structure

Standard Payload Format

Every webhook delivery contains a JSON object with the following structure:

{
  "webhookId": 123,
  "events": [
    {
      "id": 45678,
      "createdAt": "2026-01-22T10:15:30.123456Z",
      "type": "transactions.credits.created",
      "data": {
        "state": "REQUESTED"
        "transactionId": "41fc05d5-3148-4ee2-bfdf-9ad5ab7172c6"
      }
    },
    {
      "id": 45679,
      "createdAt": "2026-01-22T10:16:45.789012Z",
      "type": "transactions.debits.created",
      "data": {
        "state": "REQUESTED"
        "transactionId": "41fc05d5-3148-4ee2-bfdf-9ad5ab7172c7"
      }
    }
  ]
}

Payload Fields

Field	Type	Description
webhookId	integer	The internal ID of the webhook configuration that triggered this delivery
events	array	Array of event objects (1 to max_batch_size events)

Event Object Structure

Each event in the events array contains:

Field	Type	Description
id	integer	Unique, monotonically increasing event ID
createdAt	string	ISO 8601 timestamp with microsecond precision
type	string	Event type identifier (see Event Types Reference)
data	object	Event-specific data payload (structure varies by event type)

HTTP Headers

Every webhook request includes:

Header	Value	Description
Content-Type	application/json	Payload format
Authorization	Bearer <JWT>	Signed JWT token for authentication

If you configured a callback_api_key, it will be included in an additional header (check your implementation for the specific header name).

Event Ordering

Events within a batch are ordered ascending by their id field. Event IDs are never skipped or reused, guaranteeing a clear sequence. The last_sent_event_id field on your webhook configuration always reflects the highest event ID successfully delivered.

Batch Size

A webhook delivery contains between 1 and max_batch_size events. The actual number depends on:

How many undelivered events are available

Whether max_wait_seconds elapsed before max_batch_size was reached