# Checkout Page Webhooks

## When to Use This Skill

* How do I receive Checkout Page webhooks?
* How do I verify Checkout Page webhook signatures (the `x-webhook-signature` header)?
* How do I handle `payment.paid`, `booking.created`, or `subscription.canceled` events?
* Why is my Checkout Page webhook signature verification failing?
* How do I dedupe Checkout Page webhook retries (`eventId`)?

## Verification (core)

Every store-level webhook carries `x-webhook-signature: sha256=<64 hex>`: the lowercase hex
HMAC-SHA256 of the **raw request body bytes**, keyed with the webhook's signing secret (its UTF-8
bytes, used as-is). Nothing else is signed: `x-webhook-timestamp` is sent but is **not** part of the
signed content, so there is no signed replay window. It is not Standard Webhooks.

Node:

```javascript
const crypto = require('crypto');

function verifyCheckoutPageWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  // Accept "sha256=<hex>" or the bare digest; validate length + alphabet before decoding
  const match = /^(?:sha256=)?([0-9a-fA-F]{64})$/.exec(signatureHeader.trim());
  if (!match) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest(); // rawBody: Buffer
  return crypto.timingSafeEqual(Buffer.from(match[1].toLowerCase(), 'hex'), expected);
}

```

Python:

```python
import hashlib, hmac, re

def verify_checkout_page_webhook(raw_body: bytes, signature_header: str | None, secret: str | None) -> bool:
    if not signature_header or not secret:
        return False
    match = re.fullmatch(r"(?:sha256=)?([0-9a-fA-F]{64})", signature_header.strip())
    if not match:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(bytes.fromhex(match.group(1)), expected)

```

Verify the exact bytes received, before parsing (`express.raw({ type: '*/*' })` in Express,
`await request.arrayBuffer()` in Next.js, `await request.body()` in FastAPI). Missing, malformed or
mismatched signature: respond `401`.

> **For complete handlers with route wiring, event dispatch, and tests**, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-page-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-page-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-page-webhooks/examples/fastapi/)

## Common Event Types

The event type is the body's top-level `event` field (no header carries it). The envelope is
`sellerId`, `timestamp`, `eventId`, `event`, and `data` (the resource under its own key, e.g.
`data.booking`). The legacy `seller_id` and `event_id` fields are deprecated.

| Event | Triggered When |
| --- | --- |
| `payment.created` / `payment.paid` / `payment.abandoned` | A payment is started, completed, or abandoned |
| `booking.created` / `booking.paid` / `booking.abandoned` | A booking is made, paid, or abandoned |
| `subscription.created` / `trialing` / `scheduled` / `active` / `completed` / `canceled` / `expired` / `abandoned` | A subscription changes state (all prefixed `subscription.`) |
| `customer.created` / `customer.updated` | A customer is created or changed |
| `submission.created` / `submission.updated` | A form submission is created or changed |
| `ticket.created` | A ticket is issued |
| `product.created` / `product.updated` | A product changes |
| `checkout_page.created` / `checkout_page.updated` | A checkout page changes |

Page-level webhooks (a page's After payment > Integrations) are different: they send a single
`conversion` event with a different body. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-page-webhooks/references/overview.md).

## Delivery and Idempotency

Deliveries may be retried: dedupe on `eventId`. `x-webhook-delivery-attempt` carries the attempt
number. After a secret rotation the old secret stops working immediately; rejected deliveries are
retried briefly and then not sent again.

## Important Headers

| Header | Description |
| --- | --- |
| `x-webhook-signature` | `sha256=<hex>` HMAC-SHA256 of the raw body |
| `x-webhook-timestamp` | Unix time sent (NOT signed) |
| `x-webhook-delivery-attempt` | Attempt number (1, 2, 3, ...) |

## Environment Variables

```bash
CHECKOUT_PAGE_WEBHOOK_SECRET=your_signing_secret   # Settings > Webhooks > View signing secret

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 checkout-page --path /webhooks/checkout-page

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-page-webhooks/references/overview.md) - Events, envelope, store vs page webhooks
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-page-webhooks/references/setup.md) - Create a webhook and get the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-page-webhooks/references/verification.md) - Signature verification details and gotchas