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

# Webhook events

Cheddar delivers webhooks via [Svix](https://www.svix.com/). 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](/guides/webhooks).

## Event catalogs

| Area                                  | Page                                    | Svix `eventType` prefix                                        |
| ------------------------------------- | --------------------------------------- | -------------------------------------------------------------- |
| Customer deposits, withdrawals, swaps | [Custodial events](/webhooks/custodial) | `CUSTOMER_*`, `customer_swap.failed`, `gas_wallet.low_balance` |
| Checkout sessions and payments        | [Checkout events](/webhooks/checkout)   | `checkout.*`                                                   |

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](/webhooks/custodial) 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:

```ts
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}`.