Agent skill
Checkout Page Webhooks Skill
Receive and verify Checkout Page (checkoutpage.com) webhooks. Use when setting up Checkout Page webhook handlers, debugging x-webhook-signature verification, or handling events like payment.paid, booking.created, subscription.canceled, customer.created, and submission.created.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-signatureheader)? - How do I handle
payment.paid,booking.created, orsubscription.canceledevents? - 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:
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:
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:
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.
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
CHECKOUT_PAGE_WEBHOOK_SECRET=your_signing_secret # Settings > Webhooks > View signing secret
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 checkout-page --path /webhooks/checkout-page
Reference Materials
- references/overview.md - Events, envelope, store vs page webhooks
- references/setup.md - Create a webhook and get the signing secret
- references/verification.md - Signature verification details and gotchas