Skip to main content
Webhooks let Ledger push real-time events to your HTTPS endpoint instead of requiring you to poll.

​
Create a webhook

curl -X POST https://api.ledger.so/v1/webhooks \
  -H "Authorization: Bearer $LEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-webhook-1" \
  -d '{
    "url": "https://example.com/ledger/webhooks",
    "events": ["transaction.created", "transaction.completed", "customer.updated"]
  }'
Use ["*"] to subscribe to all events, or specify individual event types.

​
Events

​
Customer events

EventWhen it fires
customer.createdNew customer created via the API
customer.updatedCustomer status, KYC status, or capabilities changed

​
Transaction events

EventWhen it fires
transaction.createdNew transaction recorded — transfer initiated or crypto deposited to a wallet
transaction.updatedTransaction status changed (e.g. funds_received → payment_submitted)
transaction.completedTransaction reached a terminal state: completed, payment_processed, failed, returned, or refunded

​
Wallet events

EventWhen it fires
wallet.createdCrypto wallet provisioned
wallet.updatedWallet status changed

​
Virtual account events

EventWhen it fires
virtual_account.createdVirtual account opened with deposit instructions
virtual_account.updatedVirtual account status changed

​
Counterparty events

EventWhen it fires
counterparty.createdPayout account added for a customer

​
Other

EventWhen it fires
webhook.testManually triggered via POST /v1/webhooks/:id/test

​
Event payload

Every event is delivered as a POST request with this body: 
{
  "id": "evt_...",
  "type": "transaction.completed",
  "createdAt": 1710000000000,
  "data": {
    "id": "txn_...",
    "customerId": "cus_...",
    "type": "transfer",
    "status": "payment_processed",
    "amount": "5.0",
    "sourceCurrency": "usdc",
    "destinationCurrency": "gbp",
    "payoutAccountId": "pa_...",
    "finalAmount": "3.38",
    "exchangeFee": "0.0",
    "createdAt": 1710000000000,
    "updatedAt": 1710000100000
  }
}
The data object matches the same shape as the corresponding GET endpoint response.

​
Test your webhook

curl -X POST https://api.ledger.so/v1/webhooks/whk_.../test \
  -H "Authorization: Bearer $LEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"message": "hello"}}'

​
Retry policy

If your endpoint returns a non-2xx status code, Ledger retries with exponential backoff up to 10 attempts. View delivery history via GET /v1/webhooks/:id/deliveries.

​
Next steps