Webhooks

Webhooks tell your system when something happens: a release is approved, goes live, gets its codes; a payout is paid. Register https endpoints in Workspace › API or with /webhooks.

Deliveries#

Each delivery is a POST with a JSON body:

{
  "id": "…",
  "event": "release.live",
  "occurredAt": "2026-11-01T09:30:00.000Z",
  "organizationId": "…",
  "livemode": true,
  "data": { "releaseId": "…", "release": { "id": "…", "title": "Night Signals", "status": "LIVE" } }
}

Release events carry the release as GET /releases/{id} shows it. Answer with any 2xx within eight seconds; do slow work after answering.

A failed delivery is tried twice more, about a minute and then about fifteen minutes later; the endpoint's log in the API tab shows each try. GET /events keeps every event for 30 days, so a system that was down can catch up.

Signatures#

Check the X-Stillmore-Signature header before trusting a delivery. It reads t=<unix seconds>,v1=<hex>: an HMAC-SHA256, with the endpoint's secret, of the timestamp, a dot and the raw body (<t>.<raw body>). While a secret is rotated, two v1 signatures come; either one matching is enough.

import { verifyWebhook } from "./stillmore-api";

const rawBody = await request.text();
const ok = await verifyWebhook(rawBody, request.headers.get("x-stillmore-signature"), process.env.WEBHOOK_SECRET!);
if (!ok) return new Response("bad signature", { status: 400 });

Events#