Guide to Checkout Page Webhooks: Features and Best Practices
Checkout Page lets creators and small businesses sell products, subscriptions, event tickets and bookings from hosted checkout pages and forms, without building a store. Its webhooks report what happens on those pages: a payment goes through or is abandoned, a booking is made, a subscription starts, trials, renews or is cancelled, a ticket is issued or a form is submitted. You use them to fulfil orders, grant access, sync customers to a CRM or send abandoned-cart reminders.
Checkout Page sends two kinds of webhooks:
- Store-level webhooks (Store settings > Integrations > Webhooks) send signed
<resource>.<action>events such aspayment.paid. These are what the linked skill covers. - Page-level webhooks (a page's After payment > Integrations) send a separate
conversionevent with a different body (object,data.fields, ...). They are not covered by the store signature scheme described here.
This guide focuses on store-level webhooks: the 23 events, the sha256= signature, the unsigned timestamp header, and what happens to in-flight deliveries when you rotate the secret.
What are Checkout Page webhooks?
A store-level webhook is a URL plus a set of events. When one of those events happens anywhere in the store, Checkout Page sends a POST with a JSON body. Every delivery carries three headers:
x-webhook-signature:sha256=followed by a hex HMAC-SHA256 of the raw body.x-webhook-timestamp: the Unix time the webhook was sent. It is not part of the signed content.x-webhook-delivery-attempt:1on the first try, then2,3and so on for retries.
The body names the event in event and puts the affected resource under its own key in data, for example data.booking or data.payment.
Checkout Page webhook features
| Feature | Details |
|---|---|
| Configuration | Store settings > Integrations > Webhooks |
| Signature | hex HMAC-SHA256 |
| Signature header | x-webhook-signature, as sha256=<hex> |
| Signed content | The raw request body only |
| Unsigned headers | x-webhook-timestamp, x-webhook-delivery-attempt |
| Secret | Settings > Webhooks > View signing secret |
| Rotation | Immediate. Retries of earlier events are re-signed with the new secret |
| Body | JSON |
| Event routing | Body field event |
| Retries | Yes, counted in x-webhook-delivery-attempt. Schedule and limit not documented |
| Testing | The dashboard can send a signed test event |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
payment.created | A payment is started | Track pending orders |
payment.paid | A payment succeeds | Fulfil orders, grant access |
payment.abandoned | A payment is abandoned | Recovery emails |
booking.created | A booking is made | Calendar / CRM sync |
booking.paid | A booking is paid | Confirm the booking |
booking.abandoned | A booking is abandoned | Follow-up |
subscription.created | A subscription is created | Provision account |
subscription.trialing | A subscription enters a trial | Trial onboarding |
subscription.scheduled | A subscription is scheduled | Prepare start |
subscription.active | A subscription becomes active | Enable features |
subscription.completed | A subscription completes | Wind down |
subscription.canceled | A subscription is cancelled | Revoke access at period end |
subscription.expired | A subscription expires | Revoke access |
subscription.abandoned | A subscription checkout is abandoned | Follow-up |
customer.created / customer.updated | A customer is created or changed | Sync to CRM |
submission.created / submission.updated | A form submission is created or changed | Lead capture |
ticket.created | A ticket is issued | Send tickets |
product.created / product.updated | A product changes | Catalogue sync |
checkout_page.created / checkout_page.updated | A checkout page changes | Audit |
That is the full documented list of 23 events.
The subscription events track a lifecycle rather than single moments. A subscription is created when the customer submits the checkout, and can then become trialing, scheduled or active depending on how the plan is set up. subscription.completed means every payment in a payment plan has been made. subscription.canceled can mean immediate cancellation or cancellation at the end of the period, and subscription.expired fires when a cancelled subscription reaches its end date. Grant and revoke access on active and expired, not on canceled.
checkout_page.updated also fires when a page is archived or restored. Changes to a page's product send product.updated instead.
Event Payload Structure
eventcarries the type; no header names it.dataholds the resource under its own key (e.g.data.booking).seller_idandevent_idare deprecated duplicates ofsellerIdandeventId.- Deliveries may be retried: dedupe on
eventId.x-webhook-delivery-attemptis the attempt number.
Checkout Page's event reference renders its examples from a schema with "string" placeholders, so use the dashboard's test event or a real delivery to see actual values.
Setting up Checkout Page webhooks
- Open Store settings > Integrations > Webhooks.
- Add your endpoint URL, for example
https://example.com/webhooks/checkout-page. Deliveries arePOST. - Choose the events to receive, for example
payment.paid,booking.createdandsubscription.canceled. - Go to Settings > Webhooks, choose View signing secret and copy it.
- Set it as
WEBHOOK_SECRET. Use it as-is (its UTF-8 bytes); do not hex- or base64-decode it. - Send a test event from the dashboard. It is signed, so it checks your verification code as well as your URL.
Page-level webhooks (a page's After payment > Integrations) are configured separately and send a conversion event instead; they are not signed with the scheme in the linked skill.
To receive test events on your machine, forward them with the Hookdeck CLI:
npx hookdeck-cli listen 3000 checkout-page --path /webhooks/checkout-page
Securing Checkout Page webhooks
Strip sha256= from x-webhook-signature, compute an HMAC-SHA256 of the raw body with the signing secret, encode it as hex and compare in constant time. Ignore x-webhook-timestamp for verification: Checkout Page doesn't include it in what it signs. See the verification documentation.
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-webhook-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler below verifies, deduplicates on eventId, and routes the commerce events that change what a customer can access. It logs the delivery attempt, which helps when you're investigating a retry.
const express = require('express');
function createCheckoutPageApp({ seen, orders, access }) {
const app = express();
app.post('/webhooks/checkout-page', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let parsed;
try {
parsed = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
const { eventId, event, data } = parsed;
if (!eventId || typeof event !== 'string' || !data || typeof data !== 'object') {
return res.sendStatus(400);
}
console.log(`checkout-page ${event} attempt ${req.get('x-webhook-delivery-attempt')}`);
try {
if (await seen(eventId)) return res.sendStatus(200);
if (event === 'payment.paid' || event === 'booking.paid') await orders.fulfil(eventId, data);
else if (event === 'subscription.active') await access.grant(data.subscription);
else if (event === 'subscription.expired') await access.revoke(data.subscription);
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
Because the timestamp header is unsigned, anyone can change it, so it's no basis for a replay check. Deduplicate on eventId instead.
Hookdeck's Checkout Page source type reads the sha256= value and verifies it as a hex HMAC-SHA256 of the raw body, ignoring x-webhook-timestamp as Checkout Page does. Hookdeck always answers with 200, records a failed check as failed verification and does not forward that request. No timestamp window is applied.
Make Checkout Page webhooks production-ready. Hookdeck Event Gateway verifies every store webhook, keeps each payment, booking and subscription event, and retries delivery to your fulfilment service until it succeeds.
Checkout Page webhook limitations and pain points
Rotation cuts over instantly
The Problem: You rotate the signing secret and a batch of deliveries fails verification, then never comes back.
Why It Happens: Rotation is immediate: the old secret stops working at once, and retries of earlier events are re-signed with the new secret. If your receiver still has the old secret, those deliveries fail, and Checkout Page says rejected deliveries after a rotation are retried briefly and then not sent again.
Workarounds:
- Rotate during a quiet period.
- Update
WEBHOOK_SECRET(or your Hookdeck source's secret) immediately after rotating. - Reconcile payments and subscriptions from the API for the rotation window.
How Hookdeck Can Help: With Hookdeck in front, update the secret on the source and use Hookdeck's request log to find any deliveries that failed verification during the switch.
Retry policy is undocumented
The Problem: You can't tell how long Checkout Page will keep trying after your service fails.
Why It Happens: The docs say deliveries may be retried and give the attempt number in a header, but not the schedule, the attempt limit or the timeout.
Workarounds:
- Answer quickly and assume retries are limited.
- Treat
payment.paidas the trigger for fulfilment, and reconcile against the API for anything missed.
How Hookdeck Can Help: Hookdeck accepts each delivery immediately and applies a retry policy you define, so you're no longer relying on Checkout Page's.
Page-level webhooks are a different thing
The Problem: A webhook you set up on a single checkout page doesn't match any of the documented events or verify the same way.
Why It Happens: Page-level webhooks send a single conversion event with a different body, and Checkout Page does not say whether they carry x-webhook-signature.
Workarounds:
- Use store-level webhooks for anything that needs to be verified.
- If you must use page-level webhooks, keep them on a separate endpoint and inspect what arrives before trusting it.
How Hookdeck Can Help: Send page-level webhooks to a separate Hookdeck source, so their format and verification never mix with the store events.
An unsigned timestamp that looks like a replay guard
The Problem: A replay check based on x-webhook-timestamp gives a false sense of security.
Why It Happens: The timestamp header is sent but not signed. An attacker replaying a captured body can set it to anything.
Workarounds:
- Use
eventIdfor idempotency. - Keep the endpoint on HTTPS so bodies can't be captured in transit.
How Hookdeck Can Help: Hookdeck's deduplication can drop deliveries that repeat an eventId before they reach your service.
Best practices
Verify the raw body
Never JSON.parse and re-serialise before verifying. Use express.raw({ type: '*/*' }), await request.arrayBuffer() in Next.js or await request.body() in FastAPI. Check the digest is exactly 64 hex characters before decoding it.
Use the new field names
Read eventId and sellerId. event_id and seller_id are deprecated duplicates and may disappear.
Grant access on state, not on intent
Fulfil on payment.paid and booking.paid, not on .created. For subscriptions, give access on active and take it away on expired, because canceled can mean "at the end of the period".
Use the abandoned events sparingly
payment.abandoned, booking.abandoned and subscription.abandoned are useful for recovery emails. Rate-limit what you send and stop if a later paid event arrives for the same customer.
Deduplicate and process asynchronously
Store eventId with the result and return 200 quickly. Our guides to idempotency and asynchronous processing go into more detail.
Conclusion
Checkout Page's store webhooks give you a complete picture of payments, bookings and subscriptions, signed with a plain sha256= HMAC over the body. Ignore the unsigned timestamp, deduplicate on eventId, and treat secret rotation as a change to make carefully, because in-flight deliveries move to the new secret immediately.
Hookdeck Event Gateway verifies each delivery, keeps a full log of what Checkout Page sent, and retries your service on your terms.
Get started with Hookdeck for free and handle Checkout Page webhooks reliably in minutes.