Skip to content
HookDeploy

Checkout.com webhooks

Last verified against Checkout.com's documentation on September 27, 2026.

On this page ↓

Checkout.com delivers webhooks through workflows: you set conditions, such as event types and entities, and a webhook action posts matching events to your URL. Each request is signed with an HMAC of the body in the Cko-Signature header, using a key you choose in the workflow. Checkout.com resends a failed webhook up to eight times and then cancels it. This page covers what Checkout.com sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Checkout.com sends webhooks for

AreaExample eventsTypical use
Paymentspayment_approved, payment_captured, payment_declined, payment_refunded, payment_voidedFulfill orders and record refunds
Disputesdispute_received, dispute_won, dispute_lostRespond to disputes

Each webhook is a JSON POST with an event id, a type, a created_on timestamp, and the details under data.

How Checkout.com delivers webhooks

BehaviorDetail
DeliveryWorkflows. A webhook action posts events that match the workflow’s conditions
Signature headerCko-Signature: hex HMAC-SHA256 of the body, keyed with the key you set in the workflow’s webhook action
SuccessA 2xx acknowledgment
RetriesUp to eight resends at increasing intervals. If all fail, the webhook is cancelled
Manual resendFrom the Dashboard or the API
Source IPsPublished, separately for sandbox and production
DeduplicationThe event id

Common Checkout.com webhook errors and how to fix them

Signature doesn’t match

  • Wrong key. The HMAC key is the one set in the workflow’s webhook action, not your API secret key.
  • Parsed body. Hash the raw bytes.
  • Encoding. The header is hex.

Events never arrive

Check the workflow’s conditions. A webhook is only sent when an event matches every condition on an active workflow.

Webhooks cancelled after an outage

After eight failed resends, Checkout.com cancels the webhook. Resend it from the Dashboard or API once your endpoint is back.

Duplicate events

Retries and manual resends deliver the same event again. Deduplicate on the event id.

Why use HookDeploy with Checkout.com

Capture every event

HookDeploy captures every Checkout.com webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down for longer than Checkout.com’s eight resends, the events are still in HookDeploy.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

One webhook, many systems

Send each Checkout.com event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Checkout.com can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Checkout.com events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Checkout.com events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then the signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Checkout.com treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Checkout.com’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and Cko-Signature header unchanged, so retries and replays verify like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks the signature.

Checkout.com’s resends, HookDeploy’s retries, and replays can all deliver the same event. Deduplicate on the event id.

Set up Checkout.com with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Checkout.com production) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. In the Checkout.com Dashboard, create a workflow with the conditions you want, add a webhook action with your HookDeploy URL, and set its signature key.
  4. Trigger a matching event in sandbox, and confirm it appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/checkout', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.CKO_WEBHOOK_KEY)   // the key from the workflow's webhook action
    .update(req.body)
    .digest('hex');
  const received = req.get('cko-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({ eventId: event.id, type: event.type, data: event.data });
  // Deduplicate on eventId in your worker.
});

FAQ

How do I verify a Checkout.com webhook?

Compute a hex HMAC-SHA256 of the raw request body using the key you set in the workflow's webhook action, and compare it to the Cko-Signature header.

Which key signs Checkout.com webhooks?

The signature key you configure in the workflow's webhook action. It isn't your API secret key.

How many times does Checkout.com retry a webhook?

Up to eight times at increasing intervals. If every attempt fails, the webhook is cancelled, and you can resend it from the Dashboard or the API.

Why am I not receiving Checkout.com webhooks?

Webhooks are sent by workflows, so an event has to match the conditions of an active workflow with a webhook action. Check the workflow's conditions first.

How do I deduplicate Checkout.com webhooks?

Use the event id, which stays the same across retries and resends.

Does HookDeploy break Checkout.com signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and Cko-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Checkout.com webhooks free

Start free