Event reference

Events are how XPay tells your server something happened: a payment succeeded, a refund landed, a customer was created. Every event delivered to your endpoint shares the same JSON envelope; what changes is the value of type and the resource carried inside data.object.

This page is the canonical list of events you can subscribe to. For the click path to subscribe, see Setting up an endpoint. For the verifier code, see Verifying signatures.

The event envelope

Every webhook delivery has the same top-level shape:

{
  "id": "evt_test_AbC123...",
  "object": "event",
  "api_version": "3.1.0",
  "created": "2026-05-01T12:00:00.000Z",
  "type": "checkout.session.completed",
  "livemode": false,
  "data": {
    "object": { "id": "cs_test_...", "object": "checkout.session" }
  }
}

The data.object is identical to what the corresponding GET endpoint returns. If you can read a Checkout Session from GET /checkout/sessions/:id, your checkout.session.completed handler can read the same fields by the same names off data.object.

Checkout Session events

Fire on the lifecycle of a Checkout SessionAPI. These are the events most integrations key off.

Subscribe to checkout.session.completed to fulfill the order. The payload carries the resolved paymentIntent, customer, and lineItems, so a single event is enough for most fulfillment logic. lineItems lists only what the customer bought; optional add-ons they didn't add aren't included.

Charge events

Fire on the lifecycle of a ChargeAPI. A Charge is one attempt to move money on the customer's payment method. A successful payment produces one Charge; a customer who retried after a decline produces several.

Use charge.* events when your data model tracks money at the charge level (e.g. multiple captures, retried payments). For most integrations, listening to checkout.session.completed and refund.* is enough.

Refund events

Fire on the lifecycle of a RefundAPI.

Both API-issued and dashboard-issued refunds emit these. See Refunds for the API path.

charge.refunded (above) carries the parent Charge with the new Refund nested inside refunds.data, so you can key fulfillment off either side depending on which entity your data model tracks.

Customer events

Fire on the lifecycle of a CustomerAPI.

For the difference between Registered and Guest customers, and how guest matching works, see Customer lifecycle.

Webhook monitoring

When a delivery exhausts all retries, XPay emails your account's owners, admins, and developers. The email names the endpoint URL and the event type that couldn't be delivered, so you know which integration to look at. These alerts cover Live mode deliveries only. Failures come by email rather than a webhook on purpose, since a webhook to a broken endpoint would just fail too.

For the retry schedule behind that alert, and how to replay a delivery once you've fixed the handler, see Replaying & retries.

Order on a successful payment

A single payment fires more than one event. They arrive close together but not necessarily in order; treat each event as independent and dedup on event.id.

For a refund:

You don't need to listen to all of them. Pick the events your data model needs and ignore the rest.

Reading data.object

The data.object field is the same shape you'd get from the matching GET endpoint. Don't reach for the API to re-fetch a resource right after receiving its event; the payload already has everything that endpoint would return.

For the canonical shape of each resource, see the API Reference Object pages:

• Checkout SessionAPI
• Payment IntentAPI
• ChargeAPI
• RefundAPI
• CustomerAPI

For how those resources fit together (and which IDs to keep on your order record), see Object model.

Idempotency reminder

Every event can be delivered more than once: XPay retries on non-2xx, you may manually replay from the Workbench, and a successful response that didn't make it back to XPay produces a duplicate. Use event.id as the dedup key in your handler.

For the full pattern, see Verifying signatures → Idempotency.

Where to next