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-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:

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.

EventTriggered When
payment.created / payment.paid / payment.abandonedA payment is started, completed, or abandoned
booking.created / booking.paid / booking.abandonedA booking is made, paid, or abandoned
subscription.created / trialing / scheduled / active / completed / canceled / expired / abandonedA subscription changes state (all prefixed subscription.)
customer.created / customer.updatedA customer is created or changed
submission.created / submission.updatedA form submission is created or changed
ticket.createdA ticket is issued
product.created / product.updatedA product changes
checkout_page.created / checkout_page.updatedA 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

HeaderDescription
x-webhook-signaturesha256=<hex> HMAC-SHA256 of the raw body
x-webhook-timestampUnix time sent (NOT signed)
x-webhook-delivery-attemptAttempt 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →