> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledger.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Overview

> How Ledger developer webhooks work and what gets delivered.

## Event format

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

```json theme={null}
{
  "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:

```bash theme={null}
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`.