CryptoCheckout documentation

Webhooks are how your server learns that money arrived. They’re the only signal you should fulfil orders from.

Browser callbacks fire only if the customer’s tab is still open. Webhooks arrive regardless. Fulfil from webhooks.

Set up

Build an endpoint

A public HTTPS URL that accepts POST and responds 2xx quickly.

Settings → Webhooks in the dashboard. Add the URL and copy the signing secret.

Verify every delivery

Reject anything that fails. Signatures.

Test it

Use Send test event, then make a real testnet payment.

Localhost, private IP ranges, and cloud metadata addresses are rejected. Use a tunnel like ngrok for local development.

The payload

Every webhook has the same envelope:

{
  "id": "payment_confirmed_a1b2c3d4",
  "event": "payment_confirmed",
  "created_at": "2026-08-09T14:32:11.204Z",
  "data": {
    "…": "event-specific fields"
  }
}

string

Stable per transition. Use it as your idempotency key.

string

The event type. Full list.

string

ISO 8601 timestamp.

object

Event-specific payload.

Headers

Header	Purpose
`X-Webhook-Signature`	`t=<timestamp>,v1=<hmac>` — verify this
`X-Webhook-Id`	Idempotency key, matches `id` in the body
`X-Webhook-Timestamp`	Unix seconds, same as `t`
`User-Agent`	`CryptoCheckout-Webhook/1.0`

A correct handler

import crypto from "crypto";

app.post("/webhooks/cryptocheckout",
  express.raw({ type: "application/json" }),   // raw body, not parsed
  async (req, res) => {
    // 1. Verify before anything else
    if (!verifySignature(req)) return res.status(400).send("bad signature");

    const event = JSON.parse(req.body);

    // 2. Idempotency — you will see duplicates
    if (await alreadyProcessed(event.id)) return res.sendStatus(200);

    // 3. Acknowledge fast, work later
    await enqueue(event);
    res.sendStatus(200);
  });

Three rules in that snippet, all of which matter:

Raw body

Parsing and re-serialising changes the bytes and breaks the signature.

Verify first

Before parsing, before touching your database.

Acknowledge fast

We time out at 10 seconds. Do slow work in a queue.

Signature verification in detail

With replay protection and language examples.

Get started

Core concepts

Integration

Webhooks

Your money

Dashboard

Compliance

Reference

Webhooks

Set up

The payload

Headers

A correct handler

Raw body

Verify first

Acknowledge fast

Signature verification in detail

​Set up

​The payload

​Headers

​A correct handler

Raw body

Verify first

Acknowledge fast

Signature verification in detail

Set up

The payload

Headers

A correct handler