CryptoCheckout documentation

The contract


Method	`POST`
Timeout	10 seconds
Success	Any 2xx
Retry on	Non-2xx, timeout, connection failure
Delivery guarantee	At least once

At least once, not exactly once. You will occasionally receive the same event twice. Idempotency is your responsibility.

Acknowledge fast

Ten seconds is the whole budget. Do the minimum synchronously and queue the rest.

app.post("/webhooks/cryptocheckout", express.raw({type:"application/json"}), async (req, res) => {
  if (!verify(req)) return res.status(400).send("bad signature");

  await queue.push(req.body);   // fast
  res.sendStatus(200);          // acknowledge

  // Slow work happens in the worker, not here
});

Anti-pattern to avoid: calling a payment provider, generating a PDF, or sending an email inline. Any of those can exceed the timeout, which turns a successful delivery into a retry and a duplicate.

Idempotency

Every delivery carries a stable X-Webhook-Id, which also appears as id in the body. Retries of the same event reuse it.

const seen = await db.webhookEvents.findUnique({ where: { id: event.id } });
if (seen) return res.sendStatus(200);       // already handled

await db.$transaction([
  db.webhookEvents.create({ data: { id: event.id } }),
  db.orders.update({ where: { id: event.data.orderId }, data: { status: "paid" } }),
]);

Record the ID and do the work in the same transaction. Otherwise a crash between them leaves you having recorded an event you never acted on.

When your endpoint is down

Failed deliveries are retried with backoff. If you’re down for a deploy, deliveries resume once you’re back.

Money is never at risk here. Webhooks are notifications, not settlement. A payment we failed to tell you about still arrived in your pool, and still appears in Payments and the status API. The worst case is delayed fulfilment, not lost funds.

Reconciliation

Don’t rely on webhooks alone. Two backstops worth building:

Poll for stragglers

For orders still pending after a sensible window, call the status API.

Reconcile periodically

Compare your paid orders against the dashboard’s ledger. Any gap is a webhook you missed.

Debugging

The dashboard’s Webhooks tab shows recent deliveries with response codes and bodies. Start there — most failures are a signature mismatch caused by a parsed body, or a timeout from inline work.

Signature verification

The most common source of rejected deliveries.

Get started

Core concepts

Integration

Webhooks

Your money

Dashboard

Compliance

Reference

Delivery and retries

The contract

Acknowledge fast

Idempotency

When your endpoint is down

Reconciliation

Poll for stragglers

Reconcile periodically

Debugging

Signature verification

​The contract

​Acknowledge fast

​Idempotency

​When your endpoint is down

​Reconciliation

Poll for stragglers

Reconcile periodically

​Debugging

Signature verification

The contract

Acknowledge fast

Idempotency

When your endpoint is down

Reconciliation

Debugging