Webhooks

Register an HTTPS endpoint from Settings → Webhook (or PUT /v1/webhooks with your secret key) and we’ll POST an event there whenever a session settles or expires.

Events

  • checkout.session.completed — the session settled; funds are in your wallet.
  • checkout.session.expired — the session’s time limit passed with no sufficient payment.
{
  "id": "evt_...",
  "type": "checkout.session.completed",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "data": { /* the session object — see REST API */ }
}

Verifying a delivery

Every request carries X-Zela-Checkout-Timestamp and X-Zela-Checkout-Signature — a hex HMAC-SHA256 of `${timestamp}.${rawBody}`, keyed with your webhook secret (shown once, when you set the endpoint).

import crypto from "node:crypto";

function verify(rawBody: string, timestamp: string, signature: string, secret: string) {
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  if (!ok) throw new Error("invalid signature");
  // also reject a timestamp older than a few minutes to prevent replay
}

Retries

A non-2xx response is retried on a fixed backoff: 30s, 2m, 10m, 1h, then 6h. Respond 2xx as soon as you’ve durably recorded the event — do the actual work (fulfillment, etc.) after responding, not before.

Endpoint requirements

HTTPS only, and the URL must resolve to a public address — an internal or loopback address is rejected when you set it.