Skip to main content

​
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:
HeaderDescription
X-Ledger-Event-IdUnique event identifier
X-Ledger-Event-TypeEvent type (e.g. transaction.created)
X-Ledger-SignatureHMAC signature for verification

​
Event types

EventDescription
customer.createdNew customer created
customer.updatedCustomer state changed (status, KYC, or capabilities)
wallet.createdWallet provisioned
wallet.updatedWallet status changed
virtual_account.createdVirtual account opened
virtual_account.updatedVirtual account status changed
transaction.createdNew transaction recorded (deposit or transfer)
transaction.updatedTransaction status changed
counterparty.createdCounterparty added
webhook.testTest 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", "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.