> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md).

# Wallet Webhooks

Signed notifications for every deposit and withdrawal on your wallets and customer accounts, and for every status change of a crypto withdrawal.

Two webhooks cover your wallets. Both are signed `POST`s, verified the same way.

<table><thead><tr><th width="190">Webhook</th><th>What it sends</th><th>Where it goes</th></tr></thead><tbody><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#wallet-movements">Wallet movements</a></td><td>Every deposit and withdrawal on your fiat and crypto wallets and your customer accounts</td><td>The <strong>Merchant wallet accounts</strong> webhook in Webhook Management</td></tr><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#withdrawal-status">Withdrawal status</a></td><td>Every status change of a crypto withdrawal you submit</td><td>The <code>webhookUrl</code> you pass to <a href="https://docs.ezeebit.com/wallets-and-withdrawal/submit-withdrawal.md">Submit Withdrawal</a>. Without one, the <strong>Payouts</strong> webhook in Webhook Management</td></tr></tbody></table>

Webhook Management is in the Merchant Portal under **API Management → Webhook Management**.

## Verifying the signature

Rebuild the signed string from the headers and the raw body:

```
timestamp + "\n" + nonce + "\n" + rawBody + "\n"
```

Base64-decode `Ezeebit-Signature` and verify it against that string using **SHA256withRSA** and the RSA public key of the API key that signed the delivery — each webhook below says which key that is. Fetch public keys from [Query Certificate](https://docs.ezeebit.com/payment-gateway/query-certificate.md).

Use the raw body exactly as received — do not re-serialise the JSON before hashing, or the bytes will differ and verification will fail.

## Wallet movements

Every movement into or out of your wallets is pushed to your server — fiat and crypto, deposits and withdrawals, all on one contract. Movements on your [customer accounts](https://docs.ezeebit.com/customer-accounts/overview.md) come on the same webhook, with `customerAccountId` set. The headers and retry behaviour are the same as [Order Webhooks](https://docs.ezeebit.com/payment-gateway/order-webhooks.md).

### Setup

Configure a **Merchant wallet accounts** webhook for your brand in Webhook Management. It has two parts:

* **A destination URL** — must be `https://` and at most 250 characters.
* **The API key that signs it** — you choose one of your API keys. Deliveries are signed with that key's RSA private key, and the key is named in the `Ezeebit-Certificate-SN` header on every delivery so you know which public key to verify against.

There is no per-request override. A deposit has no originating request to carry one, and a `webhookUrl` on Submit Withdrawal receives the [withdrawal status](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#withdrawal-status) events, not these.

### Headers

Sent by Ezeebit on each delivery.

<table><thead><tr><th width="260">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>Ezeebit-Certificate-SN</td><td>The API key whose RSA key signed this delivery — use it to select the public key to verify with</td></tr><tr><td>Ezeebit-Timestamp</td><td>Epoch milliseconds</td></tr><tr><td>Ezeebit-Nonce</td><td>32-character alphanumeric string, unique per delivery</td></tr><tr><td>Ezeebit-Signature</td><td>Base64 <code>SHA256withRSA</code> signature — see <a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#verifying-the-signature">Verifying the signature</a></td></tr></tbody></table>

### Payload

<table><thead><tr><th width="170">Field</th><th width="80">Type</th><th width="230">Included when</th><th>Description</th></tr></thead><tbody><tr><td>eventId</td><td>string</td><td>Always</td><td>Unique id for this delivery, <code>evt_</code> followed by 32 hex characters. Stable across retries of the same delivery.</td></tr><tr><td>event</td><td>string</td><td>Always</td><td>Always <code>WALLET_MOVEMENT_STATUS_CHANGED</code></td></tr><tr><td>direction</td><td>string</td><td>Always</td><td><code>DEPOSIT</code> or <code>WITHDRAWAL</code></td></tr><tr><td>rail</td><td>string</td><td>Always</td><td><code>FIAT</code> or <code>CRYPTO</code></td></tr><tr><td>walletId</td><td>string</td><td>Always</td><td>The wallet that moved. On a customer account, the customer's <code>walletId</code></td></tr><tr><td>reference</td><td>string</td><td>Always</td><td>Order number on a withdrawal. On a crypto deposit, the transaction hash; on a fiat deposit, the deposit reference</td></tr><tr><td>currency</td><td>string</td><td>Always</td><td><code>ZAR</code>, <code>USDT</code></td></tr><tr><td>amount</td><td>string</td><td>Always</td><td>What moved in or out of the wallet</td></tr><tr><td>feeAmount</td><td>string</td><td>Withdrawals only</td><td>Never present on a deposit</td></tr><tr><td>netAmount</td><td>string</td><td>Always</td><td>What the destination receives. Equals <code>amount</code> on a deposit</td></tr><tr><td>balanceAfter</td><td>string</td><td>Deposits and fiat withdrawals always; crypto withdrawals from <code>COMPLETED</code></td><td>Balance straight after this movement.</td></tr><tr><td>status</td><td>string</td><td>Always</td><td><code>PENDING</code>, <code>PROCESSING</code>, <code>COMPLETED</code>, <code>FAILED</code> or <code>CANCELLED</code></td></tr><tr><td>statusDetail</td><td>string</td><td>Always</td><td>The originating status verbatim, e.g. <code>REVERTED</code>, <code>REJECTED</code></td></tr><tr><td>ledgerEntryId</td><td>long</td><td>Once a ledger row exists — on crypto withdrawals, from <code>COMPLETED</code></td><td>The ledger row this movement wrote</td></tr><tr><td>movementId</td><td>long</td><td>Always</td><td>Stable identifier</td></tr><tr><td>customerAccountId</td><td>string</td><td>The movement is on a customer account</td><td>The customer account the movement belongs to. <code>walletId</code>, <code>balanceAfter</code> and <code>ledgerEntryId</code> are then that account's, not yours</td></tr><tr><td>failureReason</td><td>string</td><td><code>FAILED</code> and <code>CANCELLED</code></td><td>Why the movement did not complete</td></tr><tr><td>updatedAt</td><td>long</td><td>Always</td><td>Epoch milliseconds</td></tr><tr><td>chainInfo</td><td>object</td><td><code>rail</code> is <code>CRYPTO</code></td><td>See below</td></tr><tr><td>bankInfo</td><td>object</td><td><code>rail</code> is <code>FIAT</code></td><td>See below</td></tr></tbody></table>

### chainInfo

<table><thead><tr><th width="170">Field</th><th width="230">Included when</th><th>Description</th></tr></thead><tbody><tr><td>networkType</td><td>Always</td><td><code>ETHEREUM</code> on a withdrawal. On a deposit, the network it arrived on: <code>ETHEREUM</code>, <code>BSC</code>, <code>TRON</code> or <code>SOLANA</code></td></tr><tr><td>txHash</td><td>Once broadcast on-chain</td><td>Transaction hash</td></tr><tr><td>address</td><td>Always</td><td>Destination on a withdrawal, receiving address on a deposit</td></tr><tr><td>explorerUrl</td><td>Once <code>txHash</code> exists</td><td>Block-explorer link for the transaction</td></tr></tbody></table>

### bankInfo

<table><thead><tr><th width="170">Field</th><th width="230">Included when</th><th>Description</th></tr></thead><tbody><tr><td>bankName</td><td>Always</td><td>Destination bank</td></tr><tr><td>accountNumberMasked</td><td>Always</td><td>Last four digits only, e.g. <code>******6789</code></td></tr></tbody></table>

### Reconciling the amounts

`amount - feeAmount = netAmount` holds on both rails, even though the two charge fees in opposite directions:

* **Fiat withdrawal** — the fee is charged **on top**, so `amount` is the total debited from your wallet and `netAmount` is what you asked to withdraw.
* **Crypto withdrawal** — the fee is **deducted**, so `amount` is the gross taken from your wallet and `netAmount` is what goes on chain.

`balanceAfter` is taken from the ledger row this movement wrote, so it always agrees with what the Merchant Portal shows for the same movement.

### Which statuses you receive

<table><thead><tr><th width="210">Flow</th><th>Statuses delivered</th></tr></thead><tbody><tr><td>Crypto deposit</td><td><code>COMPLETED</code> only</td></tr><tr><td>Fiat deposit</td><td><code>COMPLETED</code> only</td></tr><tr><td>Crypto withdrawal</td><td><code>PENDING</code> → <code>PROCESSING</code> → <code>COMPLETED</code>, or <code>FAILED</code>, or <code>CANCELLED</code></td></tr><tr><td>Fiat withdrawal</td><td><code>PENDING</code> → <code>PROCESSING</code> → <code>COMPLETED</code>, or <code>FAILED</code>.</td></tr></tbody></table>

Deposits and withdrawals on a customer account follow the same flows. Transfers and conversions don't send this webhook — read them from [Wallet Transactions](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-transactions.md) or the [Customer Account Ledger](https://docs.ezeebit.com/customer-accounts/customer-account-ledger.md).

### Deduplicating

**Retries of one delivery** all carry the same `eventId`, so that alone is enough to discard a repeat of something you have already processed.

**Distinct deliveries about one movement** need `movementId` plus **`statusDetail`** — not `movementId` plus `status`. A crypto withdrawal keeps one `movementId` for its whole life, and both `SUBMITTED` and `CONFIRMING` normalise to `PROCESSING`, so those two deliveries share an identifier and a status and carry different `eventId`s. Only `statusDetail` separates them; deduplicating on `status` would silently discard the second.

### Example payloads

{% tabs %}
{% tab title="Crypto deposit" %}

```json
{
  "eventId": "evt_9f2c41a7b8d34e6fa0517c3d9b82e410",
  "event": "WALLET_MOVEMENT_STATUS_CHANGED",
  "direction": "DEPOSIT",
  "rail": "CRYPTO",
  "walletId": "9865391b-3f2a-4a2b-8c3d-abcdef123456",
  "reference": "0x4f1c...",
  "currency": "USDT",
  "amount": "250.00000000",
  "netAmount": "250.00000000",
  "balanceAfter": "1450.00000000",
  "status": "COMPLETED",
  "statusDetail": "COMPLETED",
  "ledgerEntryId": 90210,
  "movementId": 90210,
  "updatedAt": 1757846400000,
  "chainInfo": {
    "networkType": "ETHEREUM",
    "txHash": "0x4f1c...",
    "address": "0x79414140e4ab0ae4edbe6f70f6c41b07a406218c",
    "explorerUrl": "https://etherscan.io/tx/0x4f1c..."
  }
}
```

{% endtab %}

{% tab title="Customer account deposit" %}

```json
{
  "eventId": "evt_5e8b2d07c13a4f9e8b6a1d2c3f4e5a6b",
  "event": "WALLET_MOVEMENT_STATUS_CHANGED",
  "direction": "DEPOSIT",
  "rail": "CRYPTO",
  "walletId": "5d0c7e2a-4b1f-4c8e-9a3d-2f6b8e1c4a70",
  "reference": "0x8d2e...",
  "currency": "USDT",
  "amount": "250.00000000",
  "netAmount": "250.00000000",
  "balanceAfter": "250.00000000",
  "status": "COMPLETED",
  "statusDetail": "COMPLETED",
  "ledgerEntryId": 3107,
  "movementId": 3107,
  "customerAccountId": "cust-1001",
  "updatedAt": 1761800400000,
  "chainInfo": {
    "networkType": "ETHEREUM",
    "txHash": "0x8d2e...",
    "address": "0x7a3f5e2b9c1d4a6e8f0b2c4d6e8a0b1c3d5ec91e",
    "explorerUrl": "https://etherscan.io/tx/0x8d2e..."
  }
}
```

{% endtab %}

{% tab title="Crypto withdrawal, processing" %}

```json
{
  "eventId": "evt_3b71e0d95a4c42f8ae60d21f77c5b9a3",
  "event": "WALLET_MOVEMENT_STATUS_CHANGED",
  "direction": "WITHDRAWAL",
  "rail": "CRYPTO",
  "walletId": "9865391b-3f2a-4a2b-8c3d-abcdef123456",
  "reference": "WD2026091412345",
  "currency": "USDT",
  "amount": "101.50000000",
  "feeAmount": "1.50000000",
  "netAmount": "100.00000000",
  "status": "PROCESSING",
  "statusDetail": "CONFIRMING",
  "movementId": 4821,
  "updatedAt": 1757846700000,
  "chainInfo": {
    "networkType": "ETHEREUM",
    "txHash": "0x9ab3...",
    "address": "0xabc123...",
    "explorerUrl": "https://etherscan.io/tx/0x9ab3..."
  }
}
```

{% endtab %}

{% tab title="Fiat withdrawal, completed" %}

```json
{
  "eventId": "evt_c04a8e1263bf4d7a91205ef6a8331dbc",
  "event": "WALLET_MOVEMENT_STATUS_CHANGED",
  "direction": "WITHDRAWAL",
  "rail": "FIAT",
  "walletId": "b3f1c2a0-9d4e-4c8a-9f1e-1234567890ab",
  "reference": "WDR-BRD001-3C9A21F0",
  "currency": "ZAR",
  "amount": "1030.00000000",
  "feeAmount": "30.00000000",
  "netAmount": "1000.00000000",
  "balanceAfter": "170.00000000",
  "status": "COMPLETED",
  "statusDetail": "COMPLETED",
  "ledgerEntryId": 1042,
  "movementId": 1042,
  "updatedAt": 1757847000000,
  "bankInfo": {
    "bankName": "First National Bank",
    "accountNumberMasked": "******6789"
  }
}
```

{% endtab %}
{% endtabs %}

## Withdrawal status

One event for every status change of a crypto withdrawal, with `eventType` set to `withdrawal.status_changed`.

### Setup

Pass `webhookUrl` to [Submit Withdrawal](https://docs.ezeebit.com/wallets-and-withdrawal/submit-withdrawal.md). Without it, the events go to the **Payouts** webhook in Webhook Management, and if that isn't set either, none are sent.

Deliveries to your `webhookUrl` are signed with your API key named `withdrawal-webhook`. Create that key in the Merchant Portal before your first withdrawal with a `webhookUrl`, and keep its credentials: you need them to fetch its public key from Query Certificate. If the key doesn't exist when you first pass a `webhookUrl`, we create it for you. Deliveries to the Payouts webhook are signed with the key chosen for that webhook, and carry `Ezeebit-Certificate-SN` like wallet movements.

### Headers

Sent on deliveries to your `webhookUrl`.

<table><thead><tr><th width="260">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>Ezeebit-Timestamp</td><td>Epoch milliseconds</td></tr><tr><td>Ezeebit-Nonce</td><td>32-character alphanumeric string, unique per delivery</td></tr><tr><td>Ezeebit-Signature</td><td>Base64 <code>SHA256withRSA</code> signature — see <a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#verifying-the-signature">Verifying the signature</a></td></tr><tr><td>Ezeebit-Event-Id</td><td>The event's <code>eventId</code></td></tr></tbody></table>

These deliveries carry no `Ezeebit-Certificate-SN`.

### Payload

<table><thead><tr><th width="200">Field</th><th width="80">Type</th><th>Description</th></tr></thead><tbody><tr><td>eventId</td><td>string</td><td>Unique to this event: <code>evt_</code>, the order number, the status, and a random suffix. The same on every retry</td></tr><tr><td>eventType</td><td>string</td><td>Always <code>withdrawal.status_changed</code></td></tr><tr><td>timestamp</td><td>long</td><td>When the event was created, epoch milliseconds</td></tr><tr><td>data.orderNo</td><td>string</td><td>Withdrawal order number from Submit Withdrawal</td></tr><tr><td>data.idempotencyKey</td><td>string</td><td>The <code>idempotencyKey</code> you sent, if any</td></tr><tr><td>data.merchantUserId</td><td>long</td><td>The user the withdrawal was submitted under</td></tr><tr><td>data.kytTxnId</td><td>string</td><td>Travel Rule / KYT screening transaction id</td></tr><tr><td>data.status</td><td>string</td><td>The withdrawal's new status, for example <code>PENDING_APPROVAL</code>, <code>SUBMITTED</code>, <code>CONFIRMING</code>, <code>COMPLETED</code>, <code>REVERTED</code> or <code>CANCELLED</code></td></tr><tr><td>data.currencyUnit</td><td>string</td><td><code>USDT</code></td></tr><tr><td>data.cryptoAmount</td><td>decimal</td><td>Gross amount debited, fee included</td></tr><tr><td>data.feeQuoteId</td><td>long</td><td>The fee quote that priced the withdrawal</td></tr><tr><td>data.netCryptoAmount</td><td>decimal</td><td>What goes on chain</td></tr><tr><td>data.fiatUnit, data.fiatAmount</td><td></td><td>Reserved. Currently <code>ZAR</code> and <code>0</code></td></tr><tr><td>data.payInfo</td><td>object</td><td><code>networkType</code> (<code>ETHEREUM</code>) and <code>toAddress</code>, plus <code>txHash</code> and <code>explorerUrl</code> once the transaction is broadcast</td></tr><tr><td>data.failureReason</td><td>string</td><td>Why the withdrawal failed, when it did</td></tr><tr><td>data.revertReason</td><td>string</td><td>Why the withdrawal was reverted, when it was</td></tr><tr><td>data.createdAt, data.updatedAt</td><td>long</td><td>Epoch milliseconds</td></tr></tbody></table>

Fields with no value are left out. A withdrawal from a customer account carries no `customerAccountId` here, so match it on `orderNo`, which Submit Withdrawal returns alongside the `customerAccountId`. The wallet movements webhook does carry `customerAccountId`.

Each event has its own `eventId`, also sent as `Ezeebit-Event-Id`, and its retries carry the same one. Deduplicate on it.

### Example payload

```json
{
  "eventId": "evt_WD2026082012345_COMPLETED_7c1e9a4b2d3f",
  "eventType": "withdrawal.status_changed",
  "timestamp": 1757847000000,
  "data": {
    "orderNo": "WD2026082012345",
    "idempotencyKey": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "merchantUserId": 10231,
    "kytTxnId": "TR2026082012345a1b2c3d4",
    "status": "COMPLETED",
    "currencyUnit": "USDT",
    "cryptoAmount": 101.50,
    "feeQuoteId": 48291,
    "netCryptoAmount": 100.00,
    "fiatUnit": "ZAR",
    "fiatAmount": 0,
    "payInfo": {
      "networkType": "ETHEREUM",
      "toAddress": "0xabc123...",
      "txHash": "0x9ab3...",
      "explorerUrl": "https://etherscan.io/tx/0x9ab3..."
    },
    "createdAt": 1757846400000,
    "updatedAt": 1757847000000
  }
}
```

## Delivery and retries

Both webhooks are delivered the same way. Return `2xx` quickly and process asynchronously. Our read timeout is **10 seconds.**

A non-2xx or a timeout is retried up to **8 attempts** in total, backing off from 1 minute and doubling each time — 1, 2, 4, 8, 16, 32, 64 minutes — capped at 128 minutes between attempts. After the last attempt the delivery is marked permanently failed and the order will need to be handled by support if required.
