Gareth Wilson Gareth Wilson

Guide to Checkout Page Webhooks: Features and Best Practices

Published


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 as payment.paid. These are what the linked skill covers.
  • Page-level webhooks (a page's After payment > Integrations) send a separate conversion event 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: 1 on the first try, then 2, 3 and 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

FeatureDetails
ConfigurationStore settings > Integrations > Webhooks
Signaturehex HMAC-SHA256
Signature headerx-webhook-signature, as sha256=<hex>
Signed contentThe raw request body only
Unsigned headersx-webhook-timestamp, x-webhook-delivery-attempt
SecretSettings > Webhooks > View signing secret
RotationImmediate. Retries of earlier events are re-signed with the new secret
BodyJSON
Event routingBody field event
RetriesYes, counted in x-webhook-delivery-attempt. Schedule and limit not documented
TestingThe dashboard can send a signed test event

Events and payloads

EventTriggered WhenCommon Use Cases
payment.createdA payment is startedTrack pending orders
payment.paidA payment succeedsFulfil orders, grant access
payment.abandonedA payment is abandonedRecovery emails
booking.createdA booking is madeCalendar / CRM sync
booking.paidA booking is paidConfirm the booking
booking.abandonedA booking is abandonedFollow-up
subscription.createdA subscription is createdProvision account
subscription.trialingA subscription enters a trialTrial onboarding
subscription.scheduledA subscription is scheduledPrepare start
subscription.activeA subscription becomes activeEnable features
subscription.completedA subscription completesWind down
subscription.canceledA subscription is cancelledRevoke access at period end
subscription.expiredA subscription expiresRevoke access
subscription.abandonedA subscription checkout is abandonedFollow-up
customer.created / customer.updatedA customer is created or changedSync to CRM
submission.created / submission.updatedA form submission is created or changedLead capture
ticket.createdA ticket is issuedSend tickets
product.created / product.updatedA product changesCatalogue sync
checkout_page.created / checkout_page.updatedA checkout page changesAudit

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

  • event carries the type; no header names it.
  • data holds the resource under its own key (e.g. data.booking).
  • seller_id and event_id are deprecated duplicates of sellerId and eventId.
  • Deliveries may be retried: dedupe on eventId. x-webhook-delivery-attempt is 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

  1. Open Store settings > Integrations > Webhooks.
  2. Add your endpoint URL, for example https://example.com/webhooks/checkout-page. Deliveries are POST.
  3. Choose the events to receive, for example payment.paid, booking.created and subscription.canceled.
  4. Go to Settings > Webhooks, choose View signing secret and copy it.
  5. Set it as WEBHOOK_SECRET. Use it as-is (its UTF-8 bytes); do not hex- or base64-decode it.
  6. 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.paid as 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 eventId for 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.