Event catalogue

Every webhook event uses the standard envelope. The table below lists every event type currently emitted, grouped by resource.

Subscribe to the events you care about when creating a webhook endpoint — do not subscribe to *. Fine-grained subscriptions are cheaper, faster, and easier to debug.

Payments

Event	When it fires	`data.object`
`payment.succeeded`	Gateway confirmed a successful capture.	`Payment`
`payment.failed`	Gateway declined, returned an error, or timed out.	`Payment`
`payment.refunded`	Full or partial refund was issued.	`Payment`
`payment.voided`	Pre-settlement void succeeded.	`Payment`
`charge.captured`	Auth was captured (deferred capture flows).	`Charge`
`charge.dispute.created`	Cardholder initiated a dispute / chargeback.	`Dispute`
`charge.dispute.updated`	Dispute state changed (evidence required, won, lost).	`Dispute`
`refund.created`	Refund was accepted by the gateway.	`Refund`
`refund.succeeded`	Refund settled successfully.	`Refund`
`refund.failed`	Refund rejected or settlement failed.	`Refund`

See the payment.succeeded example for a full payload.

Invoices

Event	When it fires	`data.object`
`invoice.finalized`	Invoice moved from `draft` to `open`.	`Invoice`
`invoice.sent`	Invoice email / SMS / WhatsApp was sent to the customer.	`Invoice`
`invoice.paid`	Invoice fully paid.	`Invoice`
`invoice.payment_failed`	A collection attempt failed — entry point to dunning.	`Invoice`
`invoice.voided`	Invoice was voided before payment.	`Invoice`
`invoice.uncollectible`	Invoice written off after failed collection.	`Invoice`
`credit_note.issued`	Credit note issued against a paid invoice.	`CreditNote`

See the invoice.paid example for a full payload.

Direct Debit mandates

Event	When it fires	`data.object`
`mandate.created`	Mandate submitted to Bacs. Not collectable yet.	`Mandate`
`mandate.activated`	Mandate lodged and Active. Collections may start after advance notice.	`Mandate`
`mandate.auddis_rejected`	Bacs AUDDIS rejected the instruction.	`Mandate`
`mandate.suspended`	Collections paused.	`Mandate`
`mandate.cancelled`	Authority ended.	`Mandate`

Wait for mandate.activated before collecting. mandate.created is not permission to debit.

Direct Debit collections

Event	When it fires	`data.object`
`collection.scheduled`	A collection was queued against an Active mandate.	`Collection`
`collection.notice_sent`	Advance notice was sent.	`Collection`
`collection.succeeded`	Collection settled.	`Collection`
`collection.failed`	Collection failed or was returned.	`Collection`
`collection.indemnity_claimed`	Customer or bank raised an indemnity claim.	`Collection`

Subscriptions

Event	When it fires	`data.object`
`subscription.created`	A new subscription was started.	`Subscription`
`subscription.updated`	Any field changed (plan, quantity, metadata).	`Subscription`
`subscription.renewed`	A renewal cycle was billed.	`Subscription`
`subscription.canceled`	Subscription was cancelled (immediate or end-of-period).	`Subscription`
`subscription.paused`	Subscription paused via dashboard or API.	`Subscription`
`subscription.resumed`	Previously paused subscription was resumed.	`Subscription`
`subscription.trial_will_end`	Fires 3 days before trial end.	`Subscription`

See the subscription.updated example for a full payload.

Customers

Event	When it fires	`data.object`
`customer.created`	Customer record created.	`Customer`
`customer.updated`	Customer attributes changed.	`Customer`
`customer.deleted`	Customer was hard-deleted.	`Customer`

Checkout

Event	When it fires	`data.object`
`checkout.session.completed`	Hosted checkout session was paid.	`CheckoutSession`
`checkout.session.expired`	Session hit its TTL without payment.	`CheckoutSession`
`payment_link.completed`	Customer completed a payment link flow.	`PaymentLink`

Cart sessions

Event	When it fires	`data.object`
`commerce.cart.created`	Cart was created via `POST /v2/cart-sessions`.	`CartSession`
`commerce.cart.updated`	Line items added, updated, or removed.	`CartSession`
`commerce.cart.addon_toggled`	Add-on selection changed on the cart.	`CartSession`
`commerce.cart.discount_applied`	Discount code was set or cleared.	`CartSession`
`commerce.cart.converted`	Cart converted atomically into a pending Checkout Session.	`CartSession` + `CheckoutSession`
`commerce.cart.abandoned`	Sweep transitioned a stuck open cart with line items past the inactivity cutoff (default 60 min). Subscribe to drive recovery flows.	`CartSession`

See Cart Sessions for the lifecycle and convert semantics.

Payouts

Event	When it fires	`data.object`
`payout.paid`	Funds settled to the merchant's bank account.	`Payout`
`payout.failed`	Payout rejected by the acquiring bank.	`Payout`

Terminal (card-present)

Event	When it fires	`data.object`
`terminal_payment.succeeded`	Card-present terminal charge completed.	`TerminalPayment`
`terminal_payment.failed`	Terminal charge declined or timed out.	`TerminalPayment`

Wallet & credits

Event	When it fires	`data.object`
`wallet.credit_issued`	Credit was added to a customer's wallet.	`Wallet`
`wallet.code_created`	Redemption code was minted.	`WalletCode`
`benefits.granted`	Entitlement granted to a customer.	`Entitlement`

Entitlements & usage

Event	When it fires	`data.object`
`usage.threshold.reached`	Customer exceeded a configured usage threshold.	`UsageSnapshot`
`usage.period_finalized`	A usage billing period closed and records were finalized.	`UsagePeriod`
`usage.invoice.created`	A usage-based invoice was generated from finalized records.	`UsageInvoice`
`usage.event.ingested`	A usage event was accepted. High-volume — opt in with narrow filters.	`UsageEvent`
`usage.event.rejected`	Ingestion rejected the event (validation failed). Not billable.	`UsageEvent`
`usage.event.excluded`	A meter considered the event but filter conditions excluded it.	`UsageEvent`
`usage.event.quarantined`	The event could not be matched to a single active meter.	`UsageEvent`
`usage.cap.exceeded`	A hard usage cap refused the event. Nothing persisted, nothing charged.	`UsageEvent`
`meter.created`	A usage meter was created.	`Meter`
`meter.updated`	A usage meter was updated.	`Meter`
`meter.archived`	A usage meter was archived.	`Meter`
`entitlement.expired`	Time-bounded entitlement ended.	`Entitlement`

Usage ingest events (usage.event.ingested, usage.event.excluded, usage.event.quarantined, usage.cap.exceeded) are delivered at-least-once. Dedupe on data.dedupeKey (usage:{eventId}:{kind}, or usage:batch:{index}:{kind} when no row was persisted). usage.event.ingested is high-volume — subscribe only with narrow endpoint filters.

Delivery failures (meta)

Event	When it fires	`data.object`
`endpoint.delivery.failed`	A webhook endpoint had 3+ consecutive retry failures.	`WebhookEndpoint`

Subscribe to this from a separate webhook endpoint (or an out-of-band alerting system) so you learn about outages on your primary endpoint.

Event versioning

Event payloads follow the same API versioning rules — new fields can appear at any time, existing fields never change meaning under an existing version header. Pin the endpoint's version when you create it via the dashboard or API.