Checkout.com Webhooks Skill

Checkout.com (checkout.com) is a global payments processor. It sends webhooks for payments, disputes, fraud, payouts, issuing and identity verification.

This skill targets the current ("NAS" / Workflows) platform — webhooks configured under Dashboard → Developers → Webhooks, or created as a webhook action on POST https://{prefix}.api.checkout.com/workflows. See Legacy accounts if you are on the previous ("ABC") platform.

Canonical docs: Receive webhooks and Configure your webhook server → Validate the payload.

Not Checkout Page (checkoutpage.com), not CheckoutJoy, not 2Checkout / Verifone, not Stripe Checkout, not Shopify checkout webhooks. 2Checkout (now Verifone) in particular is a different company with an entirely different INS/IPN scheme — none of this applies there.

When to Use This Skill

• How do I receive Checkout.com webhooks?
• How do I verify a Checkout.com webhook signature?
• Why is my Cko-Signature verification failing?
• How do I handle payment_approved, payment_captured or payment_declined?
• How do I handle dispute_received and the rest of the dispute lifecycle?
• What is the Authorization header Checkout.com sends on my webhooks?
• Does Checkout.com send a handshake or challenge request?
• Why does created_on sometimes not exist on a Checkout.com event?

Two Optional Mechanisms, One That Proves Integrity

Checkout.com configures two independent, optional verification mechanisms per webhook. Implement both; check whichever you have a value for.

Checkout.com, verbatim from Receive webhooks: "Checkout.com generates the HMAC by hashing the webhook payload using the key you provide in your workflow's webhook action, and then sends it in the hex-encoded (Base16) Cko-Signature header."

The Authorization key is a static bearer secret, not a signature — treat it as a complement to Cko-Signature, never a replacement. Checkout.com adds no Bearer or Basic prefix: whatever you configured is what arrives.

Users can also add arbitrary extra static headers ("Add new header" in the Dashboard). Nothing in this skill depends on them.

Verification (core)

Reference: Configure your webhook server → Validate the payload.

const crypto = require('crypto');

// Cko-Signature is HMAC-SHA256 of the RAW body, HEX-encoded (Base16).
// The bare digest: NO `sha256=` prefix, NO `t=`/timestamp, NO version tag,
// exactly ONE signature.
function verifyCkoSignature(rawBody, signatureHeader, signatureKey) {
  if (!signatureHeader || !signatureKey) return false;      // fail closed
  const expected = crypto
    .createHmac('sha256', signatureKey)  // key used AS-IS as UTF-8 — never hex/base64-decode it
    .update(rawBody)                     // RAW bytes — never re-serialized JSON
    .digest('hex');
  const a = Buffer.from(signatureHeader.trim().toLowerCase(), 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b); // length guard FIRST
}

// Optional second mechanism: the configured key arrives VERBATIM in
// Authorization (no "Bearer " prefix). Only enforced when you configured one.
function verifyAuthorizationKey(header, expectedKey) {
  if (!expectedKey) return true;                            // not configured
  const a = Buffer.from(String(header || ''), 'utf8');
  const b = Buffer.from(expectedKey, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Why manual HMAC and not an SDK

Checkout.com's official SDKs (checkout-sdk-node, checkout-sdk-python, …) manage workflows — they create and update webhook actions — but none of them ships a webhook-signature verification helper. There is nothing to call. Do the HMAC directly with node:crypto or Python hmac + hashlib, as the examples here do. Don't add checkout-sdk-node as a dependency for this.

Gotchas That Actually Bite

Use the raw body. Checkout.com is explicit: "To avoid signature verification inconsistencies, perform the signature calculation based on the raw payload body from the HTTP request." It warns that deserializing and re-serializing "could change the precision of some values" and mangle special characters (©, ®, ™). JSON.parse → JSON.stringify before hashing is the single most common cause of a failing Cko-Signature.

The key is used as-is. The signature key is a UTF-8 string (e.g. 8V8x0dLK%AyD*DNS8JJr in Checkout.com's own SDK tests) — do not base64-decode or hex-decode it before passing it to HMAC.

The signature key is not your sk_... secret API key on the current platform. It's the value generated at Dashboard → Developers → Webhooks → Create configuration → Generate key, or the signature.key you set on the workflow action. (Integrators can choose to set the signature key to their secret key — Checkout.com's WooCommerce plugin does — but that's their choice, not the default.)

Hex, not base64. digest('hex') / .hexdigest(). Lowercase in practice (Checkout.com's own WooCommerce plugin compares PHP hash_hmac('sha256', $raw, $key) with ===), but lowercase the received value before comparing anyway.

There is no timestamp and no replay window. No Cko-Timestamp header exists, and no timestamp is signed. Do not invent a tolerance check — you'd reject every delivery. Replay protection is deduplication on the event id (evt_…).

timingSafeEqual throws on length mismatch. Guard lengths first (or try/catch). An uncaught throw becomes a 500, which Checkout.com retries eight times.

The timestamp field name varies by event. payment_approved and dispute_received carry created_on; payment_captured carries timestamp. Read created_on ?? timestamp — never assume one.

amount is in the minor currency unit. "amount": 20 with "currency": "USD" is $0.20, not $20.

No handshake, no challenge, no verification request. Checkout.com never asks your endpoint to echo anything back before it starts sending. Don't write a branch for one.

Envelope

{
  "id": "evt_caxmnvuvbe4elkbdx2imwbnjxu",
  "type": "payment_approved",
  "version": "1.0.29",
  "created_on": "2023-05-22T11:56:04.8821546Z",
  "data": {
    "id": "pay_griq7wyqkggu7mnk7ecm6ysrl4",
    "action_id": "act_gl5cpqgccxeulozrvaassd4lta",
    "reference": "ORD-5023-4E89",
    "amount": 20,
    "currency": "USD",
    "response_code": "10000",
    "response_summary": "Approved",
    "metadata": { "coupon_code": "NY2018" }
  },
  "_links": {
    "self": { "href": "https://{prefix}.api.checkout.com/workflows/events/evt_caxmnvuvbe4elkbdx2imwbnjxu" }
  }
}

• id — the event id, evt_…. This is your idempotency key.
• type — a snake_case string. There are no dotted names.
• version — the event schema version (e.g. "1.0.29"), not an API version.
• created_on or timestamp — see the gotcha above.
• data.id — the payment (pay_…) for payment events, the dispute (dsp_…) for dispute events. Dispute events also carry data.payment_id.
• Some events additionally carry source and action_invocations (workflow_id / workflow_action_id / status).

Common Event Types

type values are snake_case strings — never payment.captured, never Stripe-style names.

The Event types page lists 140+ events across Authentication, Balances, Compliance, Disputes, Fraud, Gateway, Identities, Issuing, Network tokens, Platforms, Real-Time Account Updater, Reports and Settlements. Subscribe only to what you handle.

Delivery, Retries and Ordering

• Acknowledge within 10 seconds. Checkout.com: "Your webhook server must acknowledge every webhook it receives within 10 seconds." Verify, enqueue, return 2xx — do the work afterwards.
• Retries: up to 8, after the previous attempt — 5 min, 10 min, 15 min, 30 min, 1 hour, 4 hours, 12 hours, 12 hours (~30 hours total). Keep processed evt_… ids for at least 31 hours — a floor for the automatic retries, not a ceiling; longer is safer since the id is your only replay protection.
• Delivery is at-least-once and ORDER IS NOT GUARANTEED. Checkout.com: "Checkout.com guarantees to send webhooks at least once, but the order in which we send them may vary." payment_captured can arrive before payment_approved. Do not drive a state machine off arrival order.

Source IPs

Checkout.com publishes the IPs it sends webhooks from (Developer resources → IP addresses), but warns that "the provided IP address lists are subject to change" and that "you may experience access issues if you do not keep your allowlists updated." This skill deliberately hardcodes no IP list. The HMAC is the credential.

Legacy (previous platform) accounts

Checkout.com's previous ("ABC") platform configured webhooks via the old /webhooks endpoint and the Hub; its docs are no longer published. Checkout.com's Shopware 5 plugin reads the same Cko-Signature header and computes the same HMAC-SHA256 hex digest, so the header, algorithm and encoding appear unchanged (inferred from plugin source, not documented).

Inferred from Checkout.com's own Shopware 5 plugin source, not from current docs: that plugin accepts Cko-Signature if it matches HMAC-SHA256 of the raw body keyed with either the configured webhook signature key or the account's private/secret key. So: if verification fails on a previous-platform account, try your secret key as the HMAC key. Nothing more than that is asserted here — do not build a second verifier for it speculatively.

Environment Variables

# REQUIRED. The webhook "signature key": Dashboard -> Developers -> Webhooks ->
# Create configuration -> "Generate key", or actions[].signature.key on the
# Workflows API. Used AS-IS as a UTF-8 HMAC key — do NOT decode it.
# NOT your sk_... secret API key on the current platform.
CHECKOUT_WEBHOOK_SIGNATURE_KEY=8V8x0dLK%AyD*DNS8JJr

# OPTIONAL. Only set this if you configured an Authorization header key on the
# webhook. Sent VERBATIM — no "Bearer " prefix. When unset, the check is skipped.
CHECKOUT_WEBHOOK_AUTHORIZATION_KEY=

The examples fail closed: with CHECKOUT_WEBHOOK_SIGNATURE_KEY unset they reject every delivery with a clear error rather than silently skipping verification.

Local Development

npx hookdeck-cli listen 3000 checkout-com --path /webhooks/checkout-com

No account required — the CLI creates a guest account on first run and gives you a public HTTPS URL plus a web UI for inspecting requests. Paste the printed URL into the webhook's Endpoint URL in the Checkout.com Dashboard, then trigger a test payment in sandbox to get a real, signed delivery. (Use 8000 for the FastAPI example.)

Reference Materials

• references/overview.md — Envelope, event families, amount units, idempotency, retries, ordering
• references/setup.md — Dashboard configuration, generating the signature key, the Workflows API, sandbox vs live
• references/verification.md — Cko-Signature byte by byte, the Authorization key, legacy accounts, debugging failures