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.