Skip to navigation

Webhook events

Real-time notifications for custodial wallets and checkout.

Cheddar delivers webhooks via Svix. Each delivery is HMAC-signed — verify the signature before trusting the payload.

Configure your endpoint URL and view your signing secret in the dashboard — see Webhooks.

Event catalogs

AreaPageSvix eventType prefix
Customer deposits, withdrawals, swapsCustodial eventsCUSTOMER_*, customer_swap.failed, gas_wallet.low_balance
Checkout sessions and paymentsCheckout eventscheckout.*

Custodial and checkout events share one Svix application per organization (Dashboard → Custodial → Webhooks). Subscribe to the types you need on your endpoint.

The custodial events page includes an integrator mapping for deposits (no status field — use isFlagged and resolution event types).

Signature verification

Use the Svix libraries (or verify the svix-signature header manually) with your endpoint’s signing secret:

import { Webhook } from "svix";
const wh = new Webhook(SIGNING_SECRET);
const payload = wh.verify(rawBody, {
"svix-id": req.headers["svix-id"],
"svix-timestamp": req.headers["svix-timestamp"],
"svix-signature": req.headers["svix-signature"],
});

After verification, parse the JSON body. The shape depends on the event family — see the custodial or checkout catalog for examples.

Idempotency

Custodial events use deterministic Svix eventId values (for example evt_deposit_{id}, evt_withdraw_{id}). De-duplicate on eventId.

Flagged-deposit resolutions use their own ids — evt_deposit_approved_{id}, evt_deposit_rejected_{id}, evt_deposit_redirected_{id} — distinct from evt_deposit_{id} on the original deposit.

Checkout session payloads use a new random id inside the envelope on each send. De-duplicate on that id, or on business keys such as session_id plus type if you track state yourself.

Risk and quarantine checkout events use deterministic Svix eventId values of the form evt_checkout_{eventType}_{sessionId}.