Setting up an endpoint

Click Add endpoint

Top-right of the Webhooks tab. If the list is empty, the same action is on the empty state as Create webhook endpoint.

A side panel opens with two required fields: the URL and the events.

Enter the endpoint URL

Type a fully qualified URL into Endpoint URL. The form validates the shape, not reachability. The URL must be one your server actually serves.

A few rules:

• Include the protocol (https://...). The form rejects values that don't parse as URLs.
• Use HTTPS in production. Plain HTTP is accepted by the form, but a reachable HTTPS URL with a valid certificate is what you want once you ship. http://localhost:... is fine in test mode while you build (see Local development for tunnels).
• One endpoint per URL. If you need to fan out to two systems, create two endpoints with different URLs, or have one handler forward.

Pick events to listen to

Below the URL field is Select events to listen to. The picker is split into two sections:

• A Recommended section at the top, surfacing the high-signal events most integrations subscribe to first (Checkout Session completion, refund lifecycle, customer lifecycle).
• An Advanced collapsible below it that holds the rest, grouped by resource.

Click any group to expand it and tick individual events. Each group has an in-group Select all checkbox if you want every event in that group at once. The same resource can appear in both sections when its events span both buckets — Checkout Sessions, for example, shows checkout.session.completed under Recommended and the rest of its lifecycle under Advanced.

You must pick at least one. A common starting set:

• checkout.session.completed for the lifecycle of the session you created.
• refund.created and refund.failed to track reversals.
• customer.created, customer.updated, customer.deleted to keep your customer table in sync.

Add charge.succeeded / charge.failed (under Advanced → Charges) if your data model needs to react at the charge level. Subscribe only to the events your handler actually reads — every subscription costs a delivery, a retry budget, and a signature verification on your server.

For the full list, see Event reference.

Click Add endpoint to save

XPay creates the endpoint and immediately surfaces a Webhook signing secret dialog with a whsec_* value.

Copy it now. The dashboard will not show it again. If you lose it, your only path is to delete the endpoint and create a new one.

Store it on the server that runs your handler, typically as an environment variable like XPAY_WEBHOOK_SECRET loaded once at boot. Click Done to close the dialog and return to the list.