> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://doc.cheddar.biz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://doc.cheddar.biz/_mcp/server.

# Custodial webhook events

These events fire for **Default (custodial)** wallet activity. Payloads are a
flat JSON object with an `eventType` field matching the Svix event type.

Configure endpoints under **Dashboard → Custodial → Webhooks**. See
[Webhooks](/guides/webhooks) for setup and
[Webhook events](/webhooks/events) for signature verification.
For what each transaction `status` means and how long confirmation takes per
chain, see [Transaction statuses](/guides/transaction-statuses).

> **Note**
>
> **Transaction ids are UUID strings.** The deposit and withdrawal `id` (and
> `transactionId` on `CUSTOMER_WITHDRAW_AWAITING_APPROVAL`) are UUID strings such
> as `"3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c"`. Store them as strings and match on
> the exact string.

## Event catalog

| Event type                            | When                                                                                         |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `CUSTOMER_DEPOSIT_PROCESSING`         | A customer deposit is first included in a block. Informational — do not credit.              |
| `CUSTOMER_DEPOSIT`                    | A customer deposit is confirmed on-chain.                                                    |
| `CUSTOMER_DEPOSIT_FAILED`             | A processing deposit dropped out of the chain (reorg) or its result flipped. Never credited. |
| `CUSTOMER_DEPOSIT_APPROVED`           | A flagged deposit was approved and credited.                                                 |
| `CUSTOMER_DEPOSIT_REJECTED`           | A flagged deposit was returned to the sending address.                                       |
| `CUSTOMER_DEPOSIT_REDIRECTED`         | A flagged deposit was sent to a different address.                                           |
| `CUSTOMER_WITHDRAW_PROCESSING`        | A customer withdrawal is first included in a block.                                          |
| `CUSTOMER_WITHDRAW`                   | A customer withdrawal is confirmed (broadcast, on chains without confirmation tracking).     |
| `CUSTOMER_WITHDRAW_AWAITING_APPROVAL` | A withdrawal needs manual approval (threshold / low liquidity).                              |
| `CUSTOMER_FAILED_TO_WITHDRAW`         | A withdrawal failed.                                                                         |
| `customer_swap.failed`                | A [customer swap](/guides/customer-swaps) failed after being created.                        |
| `gas_wallet.low_balance`              | A gas wallet dropped below its configured threshold.                                         |

## Mapping deposits on your system

On Cheddar, a confirmed customer deposit is either **cleared** (not flagged —
balance credited) or **flagged** (held for review). Webhooks do **not** include
a `status` field for that distinction.

* **`CUSTOMER_DEPOSIT`** is sent **only after the deposit is confirmed
  on-chain**. On chains with confirmation tracking that means it reached its
  confirmation target (see [Transaction statuses](/guides/transaction-statuses)).
  **Credit only on `CUSTOMER_DEPOSIT`.**
* **`CUSTOMER_DEPOSIT_PROCESSING`** fires earlier, when the transfer is first
  included in a block. It is informational: the deposit can still fail. Processing
  is first block inclusion; there is still no mempool webhook.
* If a processing deposit drops out of the chain, **`CUSTOMER_DEPOSIT_FAILED`**
  fires instead of `CUSTOMER_DEPOSIT`, and nothing is credited.
* Risk screening and flagging happen at confirmation, so `isFlagged` and
  `riskOfFunds` are only on `CUSTOMER_DEPOSIT`.
* The same event fires for **cleared and flagged** deposits. Use **`isFlagged`**
  to tell them apart. You decide how to treat flagged deposits on your side;
  Cheddar does not skip the webhook when a deposit is held.
* After someone resolves a flagged deposit in the dashboard,
  **`CUSTOMER_DEPOSIT_APPROVED`**, **`CUSTOMER_DEPOSIT_REJECTED`**, or
  **`CUSTOMER_DEPOSIT_REDIRECTED`** follows (same deposit **`id`** as the
  original `CUSTOMER_DEPOSIT`).

| Your side (example)                | Parse                                                                            | Notes                                                                                                                                                                                                                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confirmed / credit                 | `eventType === "CUSTOMER_DEPOSIT"` and `isFlagged === false` and `swap === null` | Cheddar has confirmed and recorded the deposit. Funds are swept to your organization main wallet on the next internal transfer run. (Exception: **Require approval for every deposit** on that customer keeps the deposit flagged until you resolve it — see Test events below.) |
| Pending review / hold              | `eventType === "CUSTOMER_DEPOSIT"` and `isFlagged === true`                      | Cheddar has confirmed and recorded the deposit, but it was **flagged during risk screening**. Resolve it in the dashboard (approve, reject, or redirect). Funds **stay on the deposit wallet** and are **not** swept to your main wallet until resolution.                       |
| Swap arrival (not organic deposit) | `CUSTOMER_DEPOSIT` and `swap !== null`                                           | Destination leg of a [customer swap](/guides/customer-swaps) — not new outside money. The `swap` field is only populated when customer swaps are enabled for your org; if you do not use that product, treat `swap` as always `null` and ignore this row.                        |
| Approved (after hold)              | `CUSTOMER_DEPOSIT_APPROVED`                                                      | Emitted when the deposit is approved; no new on-chain transfer.                                                                                                                                                                                                                  |
| Rejected / returned                | `CUSTOMER_DEPOSIT_REJECTED`                                                      | Emitted after the return transaction **confirms**; includes `destinationAddress`, `txHash`.                                                                                                                                                                                      |
| Redirected                         | `CUSTOMER_DEPOSIT_REDIRECTED`                                                    | Emitted after the transfer **confirms**.                                                                                                                                                                                                                                         |

```mermaid
stateDiagram-v2
  direction LR
  OnChainConfirmed --> CustomerDeposit: CUSTOMER_DEPOSIT
  CustomerDeposit --> Cleared: isFlagged_false
  CustomerDeposit --> Held: isFlagged_true
  Held --> Approved: CUSTOMER_DEPOSIT_APPROVED
  Held --> Rejected: CUSTOMER_DEPOSIT_REJECTED
  Held --> Redirected: CUSTOMER_DEPOSIT_REDIRECTED
```

**Fields to parse**

* **`isFlagged`** — cleared-to-credit vs held on Cheddar (primary hold signal).
* **`riskOfFunds`** — sender scan severity (for example `HIGH_RISK`,
  `VERY_LOW_RISK`) or `NOT_ANALYZED` when no scan ran. Informational; do **not**
  use it instead of `isFlagged` to decide credit vs hold.
* **`id`** — UUID string; ties the initial `CUSTOMER_DEPOSIT` to resolution events.
* **`swap`** — non-null when this deposit completes a customer swap.

Withdrawals and swaps use **other** event types in the catalog above (for
example `CUSTOMER_WITHDRAW_AWAITING_APPROVAL`, `customer_swap.failed`).

> **Note**
>
> Staging often receives only `CUSTOMER_DEPOSIT` with `isFlagged: false` and
> `riskOfFunds: "NOT_ANALYZED"` when risk thresholds are unset, the amount is
> below your USD threshold, or screening does not run on testnet. That is fewer
> **deliveries**, not a shorter **catalog** — subscribe to the event types you
> need in Svix and use the table above when they arrive.

## Missed a webhook?

If your endpoint was down or retries ran out, read the current state from the
status endpoints instead: [`GET /deposits`](/guides/deposits#check-deposit-status)
and [`GET /withdrawals`](/guides/withdrawals#check-withdrawal-status). Look up by
the same `id` the webhook carries, or list by `customerId` and a `createdAt`
time window.

## Test events

Send a sample of any event above from **Dashboard → Webhooks → Send test event**.
Test payloads have the same shape as real ones, contain placeholder data
(`customerId: "test_customer"`, the all-zero UUID `00000000-0000-0000-0000-000000000000` as the id, zeroed hashes), and never touch balances.
They carry a test flag, so your handler can skip them:

* Flat payloads (every `CUSTOMER_*` event and `customer_swap.failed`) get `"isTest": true`.
* `gas_wallet.low_balance` (a `{ type, data }` envelope) gets `"is_test": true` at the top level.

Real events never include the flag, so a missing flag means the event is real.

> **Tip**
>
> To exercise the real flagged-deposit flow end to end on staging (`CUSTOMER_DEPOSIT`
> with `isFlagged: true`, then `CUSTOMER_DEPOSIT_APPROVED` / `_REJECTED` /
> `_REDIRECTED`), open a test customer under **Dashboard → Custodial → Customers** and turn on
> **Require approval for every deposit**. Every deposit to that customer is then
> held under Flagged Deposits for you to approve, reject or redirect, with
> `flagReason.entityType` set to `MANUAL_REVIEW`.

---

### `CUSTOMER_DEPOSIT_PROCESSING`

The deposit is in a block but not yet at its confirmation target. Do not credit.

```json
{
  "eventType": "CUSTOMER_DEPOSIT_PROCESSING",
  "id": 12345,
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "uiAmount": "1.00",
  "usdAmount": "1.00",
  "txHash": "0x…",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "scannerUrl": "https://etherscan.io/tx/0x…",
  "status": "PROCESSING",
  "confirmationTier": "LOW",
  "confirmationTarget": { "kind": "blocks", "blocks": 12 }
}
```

`confirmationTier` and `confirmationTarget` are the target this deposit must
reach before `CUSTOMER_DEPOSIT` fires. `confirmationTarget` is
`{ "kind": "blocks", "blocks": n }`, or `{ "kind": "finalized" }` /
`{ "kind": "confirmed" }` on chains that use finality.

---

### `CUSTOMER_DEPOSIT_FAILED`

Same fields as `CUSTOMER_DEPOSIT_PROCESSING`, with `"status": "FAILED"` and a
`reason`:

* `REORGED_OUT` — the transaction is no longer in the chain.
* `RESULT_FLIPPED` — the transaction is in the chain but now failed.

Nothing was credited. If you showed the processing deposit to your customer,
remove it.

---

### `CUSTOMER_DEPOSIT`

```json
{
  "eventType": "CUSTOMER_DEPOSIT",
  "id": "3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c",
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "uiAmount": "1.00",
  "usdAmount": "1.00",
  "txHash": "0x…",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "scannerUrl": "https://etherscan.io/tx/0x…",
  "riskOfFunds": "VERY_LOW_RISK",
  "isFlagged": false,
  "swap": null
}
```

`amount` is atomic token units. `riskOfFunds` is a Scorechain severity string
(for example `HIGH_RISK`, `VERY_LOW_RISK`) or `NOT_ANALYZED` when no scan ran.

> **Warning**
>
> When this deposit is the **destination leg** of a [customer swap](/guides/customer-swaps), `swap` is non-null instead of `null`:
>
> ```json
> "swap": {
>   "customerSwapId": "9f1e2b3a-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
>   "idempotencyKey": "unique-per-swap",
>   "fromMint": { "id": 1, "symbol": "USDC", "chain": "SOLANA" },
>   "toMint": { "id": 4, "symbol": "ETH", "chain": "ETHEREUM" },
>   "amountIn": "5000000",
>   "estimatedAmountOut": "1950000000000000000",
>   "amountOut": "1948210000000000000",
>   "originTxHash": "5s2k…",
>   "destinationTxHash": "0x…",
>   "createdAt": "2026-01-01T00:00:00.000Z"
> }
> ```
>
> If you pay a deposit bonus on `CUSTOMER_DEPOSIT`, check `swap` first — swap
> arrivals are funded from the customer's existing balance, not new outside money.

---

### `CUSTOMER_DEPOSIT_APPROVED`

Emitted when a flagged deposit is approved. No on-chain transfer — there is no
`txHash` or `destinationAddress`.

```json
{
  "eventType": "CUSTOMER_DEPOSIT_APPROVED",
  "id": "3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c",
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "uiAmount": "1.00",
  "usdAmount": "1.00",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "flagReason": {
    "score": 12,
    "severity": "HIGH",
    "entityType": "MIXER",
    "entityName": "Example Mixer"
  }
}
```

`flagReason` fields are nullable when the deposit was flagged before analysis
was stored or the provider returned no entity. `id` matches the original
`CUSTOMER_DEPOSIT`.

---

### `CUSTOMER_DEPOSIT_REJECTED`

Emitted after the return transaction **confirms on-chain**.

```json
{
  "eventType": "CUSTOMER_DEPOSIT_REJECTED",
  "id": "3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c",
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "uiAmount": "1.00",
  "usdAmount": "1.00",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "flagReason": {
    "score": 12,
    "severity": "HIGH",
    "entityType": "MIXER",
    "entityName": "Example Mixer"
  },
  "destinationAddress": "0xSender…",
  "txHash": "0x…"
}
```

---

### `CUSTOMER_DEPOSIT_REDIRECTED`

Same shape as rejected; `destinationAddress` is the operator-chosen address.
Emitted after the transfer **confirms on-chain**. `txHash` may be omitted until
broadcast completes.

---

### `CUSTOMER_WITHDRAW_PROCESSING`

The withdrawal is in a block but not yet at its confirmation target. Same
fields as `CUSTOMER_WITHDRAW`, plus `"status": "PROCESSING"`,
`confirmationTier` and `confirmationTarget`.

---

### `CUSTOMER_WITHDRAW`

On chains with confirmation tracking, `CUSTOMER_WITHDRAW` fires when the
withdrawal reaches its confirmation target — not at broadcast (this includes
Solana and Tron). On other chains it still fires when the withdrawal is
broadcast or indexed.

`toAddress` is the receiver wallet from your withdrawal request — the same value
as `toAddress` on [`POST /withdraw`](/api).

`idempotencyKey` is the reference you sent on `POST /withdraw`, unchanged, or `null`
if you sent none. It appears on every withdrawal event (including
`CUSTOMER_WITHDRAW_PROCESSING`), so you can match each event to your own record. A withdrawal retried from the dashboard keeps the same
key.

```json
{
  "eventType": "CUSTOMER_WITHDRAW",
  "id": "8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "uiAmount": "1.00",
  "usdAmount": "1.00",
  "txHash": "0x…",
  "toAddress": "0x…",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "scannerUrl": "https://etherscan.io/tx/0x…",
  "idempotencyKey": "your-withdrawal-ref-123"
}
```

---

### `CUSTOMER_WITHDRAW_AWAITING_APPROVAL`

```json
{
  "eventType": "CUSTOMER_WITHDRAW_AWAITING_APPROVAL",
  "transactionId": "8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
  "status": "AWAITING_CONFIRMATION",
  "reason": "MAIN_WITHDRAWAL_THRESHOLD",
  "toAddress": "0x…",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "idempotencyKey": "your-withdrawal-ref-123"
}
```

Approve the withdrawal in the dashboard (or via API) before it broadcasts. See
[Withdrawals & approvals](/guides/withdrawals).

---

### `CUSTOMER_FAILED_TO_WITHDRAW`

```json
{
  "eventType": "CUSTOMER_FAILED_TO_WITHDRAW",
  "id": "8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
  "mint": { "id": 1, "symbol": "USDC", "chain": "ETHEREUM" },
  "amount": "1000000",
  "txHash": "0x…",
  "toAddress": "0x…",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "customerId": "your-customer-id",
  "reason": "Insufficient liquidity",
  "idempotencyKey": "your-withdrawal-ref-123"
}
```

`txHash` is omitted when no broadcast occurred. This payload does not include
`uiAmount` or `usdAmount`. When a processing withdrawal drops out of the chain,
`reason` is `REORGED_OUT` (no longer in the chain) or `RESULT_FLIPPED` (in the
chain but now failed).

---

### `customer_swap.failed`

Svix `eventType` is `customer_swap.failed` (not `CUSTOMER_SWAP_FAILED`). The
JSON body repeats that value in `eventType`.

```json
{
  "eventType": "customer_swap.failed",
  "customerId": "your-customer-id",
  "swap": {
    "customerSwapId": "9f1e2b3a-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "idempotencyKey": "unique-per-swap",
    "fromMint": { "id": 1, "symbol": "USDC", "chain": "SOLANA" },
    "toMint": { "id": 4, "symbol": "ETH", "chain": "ETHEREUM" },
    "amountIn": "5000000",
    "estimatedAmountOut": "1950000000000000000",
    "amountOut": null,
    "originTxHash": "5s2k…",
    "destinationTxHash": null,
    "createdAt": "2026-01-01T00:00:00.000Z"
  },
  "reason": "the swap provider could not route this pair",
  "refundedAmount": "5000000",
  "createdAt": "2026-01-01T00:05:00.000Z"
}
```

`refundedAmount` is atomic source-mint units, or `null` when nothing had been
recognized at send time — poll `GET /customer-swap/{swapId}` to confirm a
refund landed.

---

### `gas_wallet.low_balance`

```json
{
  "type": "gas_wallet.low_balance",
  "data": {
    "chain": "ETHEREUM",
    "address": "0x…",
    "current_balance": "0.05",
    "threshold": "0.10",
    "warning": "Refunds and sweeps may fail if not topped up."
  }
}
```

This event uses a `type` / `data` wrapper instead of top-level `eventType`.