Receive Real-Time Payment Notifications with Webhooks

Webhooks let your backend receive instant notifications when payment events occur — no polling required. When something meaningful happens to a checkout session (a payment is detected, confirmed on-chain, or the session expires), Crypto Checkout constructs a signed JSON payload and POSTs it to every matching registered endpoint. Your server acknowledges receipt with an HTTP 2xx response and processes the event asynchronously.

How webhooks work

An event occurs

A payment-lifecycle event is triggered — for example, on-chain confirmations reach the required threshold and the session transitions to paid.

Crypto Checkout builds the payload

The event is written to the event log and a signed JSON payload is assembled with a unique id, type, createdAt timestamp, and the full session data object.

Delivery is attempted

Crypto Checkout POSTs the payload to every active endpoint whose events array includes that event type (or "*"). The request includes an HMAC-SHA256 signature header so you can verify authenticity.

Retries on failure

If your endpoint does not respond with a 2xx status code, Crypto Checkout will make up to 6 delivery attempts with exponential backoff over approximately 31 hours. After all attempts are exhausted the delivery is marked abandoned; you can replay individual events from the dashboard.

Crypto Checkout delivers events at least once. Use the id field on every event to detect and discard duplicate deliveries in your handler.

Creating a webhook endpoint

You can register an endpoint through the dashboard or the API.

Dashboard
API

Open Webhooks

Navigate to Dashboard → Webhooks and click New Endpoint.

Enter your URL

Provide a publicly reachable HTTPS URL. Crypto Checkout requires TLS — plain http:// URLs are rejected.

Select events

Choose the specific event types you want to receive, or tick All events to subscribe to everything including future event types.

Save your secret

After you click Create, the dashboard shows your webhook secret once. Copy it immediately and store it in your environment variables — it cannot be retrieved again. If you lose it, delete the endpoint and create a new one.

Send a POST request to /api/v1/webhook_endpoints with your URL and the list of event types to subscribe to:

curl -X POST https://your-domain.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-site.com/webhooks/crypto",
    "events": ["session.paid", "session.expired"]
  }'

The response includes the endpoint object plus a secret field:

{
  "id": "whe_01HXYZ",
  "object": "webhook_endpoint",
  "url": "https://your-site.com/webhooks/crypto",
  "events": ["session.paid", "session.expired"],
  "active": true,
  "secretPrefix": "whsec_ZW...",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "secret": "whsec_ZWxhc3RpY3BhbmRh..."
}

The secret field is only present on the create response. Store it in a secure environment variable (e.g. CHECKOUT_WEBHOOK_SECRET) before the response is gone.

Subscribing to events

The events array controls which event types trigger a delivery to your endpoint. You can be selective or catch-all:

// Subscribe to specific events
{ "events": ["session.paid", "session.expired", "session.underpaid"] }

// Subscribe to all current and future events
{ "events": ["*"] }

See Event Types for the full list of available event types and their payload shapes.

Testing your endpoint

Before going live, send a synthetic session.paid event to your endpoint to confirm your handler is working correctly.

Dashboard
API

Open the endpoint’s detail page and click the Test button. Crypto Checkout will POST a synthetic session.paid payload with livemode: false to your URL and display the delivery status.

curl -X POST https://your-domain.com/api/v1/webhook_endpoints/whe_01HXYZ/test \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

A successful call returns a deliveryId you can use to inspect the attempt:

{ "deliveryId": "del_01HABC" }

Run your local server through a tunnel (e.g. ngrok http 3000 or cloudflared tunnel) during development so Crypto Checkout can reach it over the public internet. Use the tunnel URL when registering your test endpoint.

Webhook endpoint object

Every endpoint is represented by the following object. The secret field is only returned on creation.

Field	Type	Description
`id`	`string`	Unique identifier for the endpoint (`whe_…`)
`object`	`string`	Always `"webhook_endpoint"`
`url`	`string`	The HTTPS URL that receives event POST requests
`events`	`string[]`	Event types this endpoint is subscribed to; `["*"]` means all events
`active`	`boolean`	When `false`, deliveries are paused but the endpoint is not deleted
`secretPrefix`	`string`	First few characters of the secret, for identification purposes
`createdAt`	`string`	ISO 8601 creation timestamp

Pausing and disabling

Set active: false on an endpoint to pause delivery without deleting it. No events will be sent while the endpoint is inactive; delivery resumes automatically when you re-enable it.

curl -X PATCH https://your-domain.com/api/v1/webhook_endpoints/whe_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Event Types

Browse every event type, see example payloads, and learn how to deduplicate deliveries

Signature Verification

Verify the HMAC-SHA256 signature on every delivery to prevent spoofed requests

​How webhooks work

​Creating a webhook endpoint

​Subscribing to events

​Testing your endpoint

​Webhook endpoint object

​Pausing and disabling

Event Types

Signature Verification

How webhooks work

Creating a webhook endpoint

Subscribing to events

Testing your endpoint

Webhook endpoint object

Pausing and disabling