# Guide to Checkout Page Webhooks: Features and Best Practices

[Checkout Page](https://checkoutpage.com) 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

| 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

* `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](/docs/cli):

```bash
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](https://checkoutpage.com/docs/api/v1/webhooks/signature).

```javascript
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.

```javascript
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](/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](/webhooks/guides/implement-webhook-idempotency) and [asynchronous processing](/webhooks/guides/why-implement-asynchronous-processing-webhooks) 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](https://hookdeck.com) verifies each delivery, keeps a full log of what Checkout Page sent, and retries your service on your terms.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Checkout Page webhooks reliably in minutes.