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

# Wallet events

> wallet.* webhooks: when a customer's wallet is created or deleted, the payload it carries, and example deliveries

Endl sends a `wallet.*` webhook when one of your customers' wallets is created or
deleted through the API. That covers both custodial wallets Endl creates and
external wallets you register.

| Event | When it fires |
| - | - |
| `wallet.created` | [Create wallet](https://docs.endl.io/api-reference/wallets/create-wallet.md) succeeded, for a custodial wallet or an external wallet |
| `wallet.deleted` | [Delete wallet](https://docs.endl.io/api-reference/wallets/delete-wallet.md) succeeded |

Both events:

* relate to one wallet, so `data.id` is its `wlt_…` id and `data.customerId` is the owning customer's `cus_…` id
* use the standard envelope, signature and retry rules from the [Webhooks guide](https://docs.endl.io/guides/webhooks.md)

**Subscribing:** use `"eventFilter": ["wallet.*"]` to receive both.

## Payload fields

| Field | Type | Sent on | Description |
| - | - | - | - |
| `id` | string | all | The wallet's id (`wlt_…`). |
| `customerId` | string | all | The customer that owns the wallet (`cus_…`). |
| `network` | string | all, when known | The chain the wallet is on, e.g. `arbitrum` or `tron`. |
| `currency` | string | all, when known | The wallet's currency, e.g. `USDC`. |
| `type` | string | all | `CUSTODIAL` for a wallet Endl holds, `EXTERNAL` for one you registered. |

Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change. **The
wallet address and balance are not in the payload** — read them with
[Get wallet](https://docs.endl.io/api-reference/wallets/get-wallet.md).

## What does not emit

* **There is no `wallet.updated`.** Renaming a wallet sends nothing.
* **Money arriving is not a wallet event.** An incoming on-chain transfer is a
  [deposit event](https://docs.endl.io/webhooks/deposit-events.md).
* **A failed create or delete sends nothing.** Only a successful call emits.

> [!WARNING]
>
> **Both events are best-effort, and both are emitted after the work has already
> succeeded.** If the emit fails the wallet still exists, or is still deleted —
> **the API response is the authority, not the event.**

## Events in detail

### wallet.created

**When:** a custodial wallet was created, or an external wallet was registered, for
a customer.

**What to do:** store the `wlt_` id against the customer. Call Get wallet if you need
the address.

```json theme={null}
{
  "eventId": "3f4a5b6c-7d8e-3f9a-8b0c-1d2e3f4a5b6c",
  "eventType": "wallet.created",
  "eventCategory": "wallet",
  "eventCreatedAt": "2026-11-03T09:41:27.316Z",
  "version": "2026-09.1",
  "data": {
    "id": "wlt_2Kd8MnPq4RsT6uVw8xYz",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "currency": "USDC",
    "network": "arbitrum",
    "type": "CUSTODIAL"
  }
}
```

An external wallet looks the same with `"type": "EXTERNAL"`:

```json theme={null}
{
  "eventId": "7b8c9d0e-1f2a-3b4c-9d5e-6f7a8b9c0d1e",
  "eventType": "wallet.created",
  "eventCategory": "wallet",
  "eventCreatedAt": "2026-11-03T09:55:02.840Z",
  "version": "2026-09.1",
  "data": {
    "id": "wlt_6Pr8St0Uv2Wx4Yz6Ab8C",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "currency": "USDT",
    "network": "tron",
    "type": "EXTERNAL"
  }
}
```

### wallet.deleted

**When:** a wallet was deleted. The payload describes the wallet as it was.

**What to do:** stop offering the wallet as a source or destination.

```json theme={null}
{
  "eventId": "c1d2e3f4-a5b6-3c7d-8e9f-0a1b2c3d4e5f",
  "eventType": "wallet.deleted",
  "eventCategory": "wallet",
  "eventCreatedAt": "2026-11-04T12:18:44.093Z",
  "version": "2026-09.1",
  "data": {
    "id": "wlt_6Pr8St0Uv2Wx4Yz6Ab8C",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "currency": "USDT",
    "network": "tron",
    "type": "EXTERNAL"
  }
}
```

## Best practices

* **Verify the signature, then deduplicate on `eventId`, then act.** Delivery is at
  least once, so the same event can arrive twice.
* **Use the API as the source of truth.** If an event is missing, the Create wallet
  or Delete wallet response, or [List wallets](https://docs.endl.io/api-reference/wallets/list-wallets.md),
  tells you the real state.
* **Subscribe with `wallet.*`** so you automatically receive new wallet events Endl
  adds later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.