# Checkout.com Webhooks

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](#legacy-previous-platform-accounts) if you are on the
> previous ("ABC") platform.
> 
> Canonical docs: [Receive webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks) and
> [Configure your webhook server → Validate the payload](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/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.

|  | Cko-Signature — primary | Authorization — optional |
| --- | --- | --- |
| Header | `Cko-Signature` | `Authorization` |
| What it is | HMAC-SHA256 of the raw body, hex (Base16) | The configured key sent verbatim |
| Proves | Sender identity and body integrity | Sender knows a shared secret. Nothing about the body. |
| Configured as | "signature key" (Dashboard) / `actions[].signature.key` (Workflows API) | `actions[].headers.Authorization` |
| Env var here | `CHECKOUT_WEBHOOK_SIGNATURE_KEY` | `CHECKOUT_WEBHOOK_AUTHORIZATION_KEY` |

Checkout.com, verbatim from [Receive webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/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](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server#Validate_the_payload).

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-com-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-com-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/checkout-com-webhooks/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

```json
{
  "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.

| Family | Events |
| --- | --- |
| Gateway — payment | `payment_approved`, `payment_declined`, `payment_pending`, `payment_paid`, `payment_expired`, `payment_canceled`, `payment_returned` |
| Gateway — capture | `payment_captured`, `payment_capture_declined`, `payment_capture_pending` |
| Gateway — refund | `payment_refunded`, `payment_refund_declined`, `payment_refund_pending` |
| Gateway — void | `payment_voided`, `payment_void_declined` |
| Gateway — auth increment | `payment_authorization_incremented`, `payment_authorization_increment_declined` |
| Gateway — card verification | `card_verified`, `card_verification_declined` |
| Disputes | `dispute_received`, `dispute_evidence_required`, `dispute_evidence_submitted`, `dispute_accepted`, `dispute_won`, `dispute_lost`, `dispute_expired`, `dispute_canceled`, `dispute_resolved` |
| Fraud | `fraud_reported` |
| Authentication | `authentication_approved`, `authentication_failed` |

The [Event types](https://www.checkout.com/docs/developer-resources/event-notifications/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](https://www.checkout.com/docs/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

```bash
# 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

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-com-webhooks/references/overview.md) — Envelope, event families, `amount` units, idempotency, retries, ordering
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-com-webhooks/references/setup.md) — Dashboard configuration, generating the signature key, the Workflows API, sandbox vs live
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/checkout-com-webhooks/references/verification.md) — `Cko-Signature` byte by byte, the `Authorization` key, legacy accounts, debugging failures