CryptoCheckout documentation

Webhooks are how your server learns that money arrived. Fulfil orders from them, not from anything that happens in the customer’s browser.

Browser callbacks fire only if the customer’s tab is still open. Webhooks do not depend on it. Fulfil from webhooks.

Delivery is best-effort, not at-least-once. A delivery record is written only after the first send is attempted, so if the internal hand-off to our delivery service fails, the event is dropped silently — it never appears in the Webhooks tab and the retry job has nothing to recover. Treat webhooks as the fast path, not the ledger: reconcile against Payments or the payment status endpoint before concluding that a payment never arrived.

Set up

Build an endpoint

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

Settings → Webhooks in the dashboard. Add the URL.Then reveal your signing secret — once — and store it where your server reads it. If you lose it, rotate it on the same page.

Verify every delivery

Reject anything that fails. Signatures.

Test it

Use Send test payload on the Webhooks tab, then make a real testnet payment.The test is a real signed delivery — same header, same envelope — with event payment.test and data.test: true. If your handler verifies it, it verifies production.

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

The payload

Every delivery has the same envelope, including the dashboard’s test send.

{
  "id": "pool.swept_9f2c1d4e",
  "event": "pool.swept",
  "created_at": "2026-08-09T14:32:11.204Z",
  "data": {
    "intentId": "9b1e3c7a-5d2f-4e8b-a1c6-3f0d2b7e4a91",
    "rail": "connect",
    "namespace": "evm",
    "status": "swept",
    "token": "USDC",
    "chainId": 8453,
    "poolAddress": "0x5f3a…c21e",
    "forwarderAddress": null,
    "paymentId": "4c1d9e0b7a2f48e6b3a5c8d1f09e7b24",
    "orderId": "order_1042",
    "expectedAmount": "49000000",
    "confirmedAmount": "49000000",
    "txHash": "0x7f3a…a2c1"
  }
}

string

Stable per transition. Use it as your idempotency key.

string

The event type — pool.deposit.confirmed, pool.swept, pool.distributed, pool.refunded, or pool.tamper_suspected. Fulfil at capture: pool.deposit.confirmed when the customer sent a plain transfer, pool.swept when they paid from a connected wallet. Full list.

string

ISO 8601 timestamp.

object

The payment. orderId is the id you passed to updateCart; match on it to find the order. Amounts are token base units as strings (6 decimals for USDC, USDT and EURC). EVM and TRON deliveries carry the same fields; pool.distributed describes a payout rather than one payment, so it carries pool fields instead.

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`

Every delivery carries these headers, including the dashboard’s test send.

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