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
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_DEPOSITis 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 onCUSTOMER_DEPOSIT.CUSTOMER_DEPOSIT_PROCESSINGfires 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_FAILEDfires instead ofCUSTOMER_DEPOSIT, and nothing is credited. - Risk screening and flagging happen at confirmation, so
isFlaggedandriskOfFundsare only onCUSTOMER_DEPOSIT. - The same event fires for cleared and flagged deposits. Use
isFlaggedto 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, orCUSTOMER_DEPOSIT_REDIRECTEDfollows (same depositidas the originalCUSTOMER_DEPOSIT).
Fields to parse
isFlagged— cleared-to-credit vs held on Cheddar (primary hold signal).riskOfFunds— sender scan severity (for exampleHIGH_RISK,VERY_LOW_RISK) orNOT_ANALYZEDwhen no scan ran. Informational; do not use it instead ofisFlaggedto decide credit vs hold.id— UUID string; ties the initialCUSTOMER_DEPOSITto 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 andcustomer_swap.failed) get"isTest": true. gas_wallet.low_balance(a{ type, data }envelope) gets"is_test": trueat 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.
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
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:
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.
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.
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.
CUSTOMER_WITHDRAW_AWAITING_APPROVAL
Approve the withdrawal in the dashboard (or via API) before it broadcasts. See Withdrawals & approvals.
CUSTOMER_FAILED_TO_WITHDRAW
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.
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
This event uses a type / data wrapper instead of top-level eventType.