Webhook Overview - Ledger

Event format

When an event occurs, Ledger sends a POST request to your webhook URL with:

{
  "id": "evt_...",
  "type": "transaction.created",
  "createdAt": 1710000000000,
  "data": { ... }
}

Headers

Every delivery includes these headers:

Header	Description
`X-Ledger-Event-Id`	Unique event identifier
`X-Ledger-Event-Type`	Event type (e.g. `transaction.created`)
`X-Ledger-Signature`	HMAC signature for verification

Event types

Event	Description
`customer.created`	New customer created
`customer.updated`	Customer state changed (status, KYC, or capabilities)
`wallet.created`	Wallet provisioned
`wallet.updated`	Wallet status changed
`virtual_account.created`	Virtual account opened
`virtual_account.updated`	Virtual account status changed
`transaction.created`	New transaction recorded (deposit or transfer)
`transaction.updated`	Transaction status changed
`transaction.completed`	Transaction reached a terminal state (completed, failed, returned, refunded)
`counterparty.created`	Counterparty added
`webhook.test`	Test event sent manually

Subscribing to events

When creating a webhook, pass the event types you want to receive:

curl -X POST https://api.ledger.so/v1/webhooks \
  -H "Authorization: Bearer $LEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ledger",
    "events": ["transaction.created", "transaction.updated", "transaction.completed", "customer.updated"]
  }'

Use "*" to subscribe to all events.

Retry policy

If your endpoint returns a non-2xx status code, Ledger retries with exponential backoff. You can view delivery history via GET /v1/webhooks/:id/deliveries.