Checkout.com webhooks
Last verified against Checkout.com's documentation on September 27, 2026.
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
| Area | Example events | Typical use |
|---|---|---|
| Payments | payment_approved, payment_captured, payment_declined, payment_refunded, payment_voided | Fulfill orders and record refunds |
| Disputes | dispute_received, dispute_won, dispute_lost | Respond 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
| Behavior | Detail |
|---|---|
| Delivery | Workflows. A webhook action posts events that match the workflow’s conditions |
| Signature header | Cko-Signature: hex HMAC-SHA256 of the body, keyed with the key you set in the workflow’s webhook action |
| Success | A 2xx acknowledgment |
| Retries | Up to eight resends at increasing intervals. If all fail, the webhook is cancelled |
| Manual resend | From the Dashboard or the API |
| Source IPs | Published, separately for sandbox and production |
| Deduplication | The 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
- In HookDeploy, create an endpoint (for example,
Checkout.com production) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- 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.
- 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.