Skip to navigation

Custodial webhook events

Customer deposits, withdrawals, swaps, and gas-wallet alerts.

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 for setup and Webhook events for signature verification. For what each transaction status means and how long confirmation takes per chain, see Transaction statuses.

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 typeWhen
CUSTOMER_DEPOSIT_PROCESSINGA customer deposit is first included in a block. Informational — do not credit.
CUSTOMER_DEPOSITA customer deposit is confirmed on-chain.
CUSTOMER_DEPOSIT_FAILEDA processing deposit dropped out of the chain (reorg) or its result flipped. Never credited.
CUSTOMER_DEPOSIT_APPROVEDA flagged deposit was approved and credited.
CUSTOMER_DEPOSIT_REJECTEDA flagged deposit was returned to the sending address.
CUSTOMER_DEPOSIT_REDIRECTEDA flagged deposit was sent to a different address.
CUSTOMER_WITHDRAW_PROCESSINGA customer withdrawal is first included in a block.
CUSTOMER_WITHDRAWA customer withdrawal is confirmed (broadcast, on chains without confirmation tracking).
CUSTOMER_WITHDRAW_AWAITING_APPROVALA withdrawal needs manual approval (threshold / low liquidity).
CUSTOMER_FAILED_TO_WITHDRAWA withdrawal failed.
customer_swap.failedA customer swap failed after being created.
gas_wallet.low_balanceA 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). 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)ParseNotes
Confirmed / crediteventType === "CUSTOMER_DEPOSIT" and isFlagged === false and swap === nullCheddar 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 / holdeventType === "CUSTOMER_DEPOSIT" and isFlagged === trueCheddar 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 !== nullDestination leg of a customer swap — 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_APPROVEDEmitted when the deposit is approved; no new on-chain transfer.
Rejected / returnedCUSTOMER_DEPOSIT_REJECTEDEmitted after the return transaction confirms; includes destinationAddress, txHash.
RedirectedCUSTOMER_DEPOSIT_REDIRECTEDEmitted after the transfer confirms.
CUSTOMER_DEPOSIT isFlagged_false isFlagged_true CUSTOMER_DEPOSIT_APPROVED CUSTOMER_DEPOSIT_REJECTED CUSTOMER_DEPOSIT_REDIRECTED OnChainConfirmed CustomerDeposit Cleared Held Approved Rejected 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).

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 and GET /withdrawals. 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.

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.

{
"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

{
"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.

When this deposit is the destination leg of a customer swap, swap is non-null instead of null:

"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.

{
"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.

{
"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.

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.

{
"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

{
"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.


CUSTOMER_FAILED_TO_WITHDRAW

{
"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.

{
"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

{
"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.