Checkout webhook events
Checkout webhooks use the same Svix application as custodial events. See Checkout links & sessions for the payment flow. For confirmation tiers and per-chain timing, see Transaction statuses.
Two payload shapes
Most checkout events use an envelope built at send time:
The data object always includes the fields below (plus event-specific
extras). Amounts are human token units (same as the checkout session), not
wei or lamports.
Risk / quarantine events use a flat payload (no envelope):
Event catalog
Breaking REST change: the minConfirmations field is removed from the
CheckoutSession response. Confirmation depth is now set per chain and
payment value (see Confirmation targets). Strict
clients that require the field must drop it.
Several checkout.* types exist in the API enum for future lifecycle hooks
(for example checkout.session.created, checkout.payment.confirming) but are
not emitted today. Subscribe only to the types above unless release notes
say otherwise.
Confirmation targets
Confirmation tracking rolls out per chain (Ethereum, BSC, Polygon, Robinhood Chain, Tron, Solana; release notes announce each one). On a chain where it is on, a payment is not counted at first block inclusion:
- The payment is seen in a block:
checkout.payment.detectedfires. The session moves toCONFIRMINGafter the payment’s risk scan, so it may still show its previous status (or a risk hold) whendetectedarrives. - Cheddar counts confirmations until the payment meets a target chosen by chain and by the payment’s USD value (see Transaction statuses for targets and expected times).
- At the target, the payment counts toward
amount_received, andcheckout.payment.completed/checkout.payment.overpaidfire as before. Settlement starts only after that. These events can therefore arrive minutes afterdetected(longer for high-value payments on slower chains). - If the payment leaves the chain first,
checkout.payment.failedfires instead. The session goes back toAWAITING_PAYMENT(orPARTIALif another payment already counted) and expires normally if its window has closed.
A CONFIRMING session does not expire while a payment is still counting
confirmations. A payment seen before the session’s expiresAt that meets its
target afterwards still completes the session. An invoice past its due date
stays open while one of its payments is still counting confirmations.
On chains without tracking, payments count at first block inclusion, as before. Some payments are counted at first inclusion even on a chain where tracking is on, when Cheddar learns of them without a block reference (for example EVM payments seen in the mempool, and some Tron and Solana payments).
Test events
Send a sample of any event in the catalog above from Dashboard → Webhooks → Send test event. Test payloads have the real shape and placeholder data, and they don’t create sessions or move funds. They carry a test flag:
- Envelope events get
"is_test": trueat the top level, next toidandtype. - Flat risk events (
checkout.flagged,checkout.flagged.platform_held,checkout.flagged.auto_returned) get"isTest": true.
Real events never include the flag, so a missing flag means the event is real.
Shared data example
The following data block is representative for envelope events (payment
completed shown; other events reuse the same core fields):
platform_fee and net_credited appear only on checkout.payment.completed
and checkout.payment.overpaid. They are estimated from org checkout config at
payment time (fee is accrued to the monthly platform bill, not deducted on-chain
from the sweep).
checkout.payment.detected / checkout.payment.failed
Same core data fields (amount_received counts confirmed payments only, so
it does not include this one), plus the payment:
checkout.payment.failed has "status": "FAILED" in transaction, and a
top-level reason: REORGED_OUT (the transaction left the chain) or
RESULT_FLIPPED (it is now reported as failed on-chain).
Each event is sent once per payment. A session can see several payments, so
key your handling on transaction.id.
checkout.payment.overpaid
Same envelope as completed. type is checkout.payment.overpaid and
overpayment_amount is greater than "0".
checkout.wrong_token_received
Same core data fields, plus:
checkout.refund.initiated
Extra fields merged into data:
(checkoutId duplicates checkout_id — both are present in the payload
today.)
checkout.refund.completed
checkout.refund.failed
checkout.flagged.accepted / checkout.flagged.rejected
Standard envelope and shared data fields. type is
checkout.flagged.accepted or checkout.flagged.rejected. Settlement or
refund is queued after the webhook.
Flat risk events
checkout.flagged (merchant review):
checkout.flagged.platform_held — same shape; status is
FLAGGED_PLATFORM_HELD.
checkout.flagged.auto_returned — same shape; status is REFUNDING
(session moves to refund after the quarantine deadline). The checkout row is
marked FLAGGED_AUTO_RETURNED in the dashboard, but that value is not sent in
this webhook.
riskFlag is the session’s stored risk metadata; fields vary by scan outcome.