DOCS · CORE WORKFLOWS

Webhooks & Deliveries

Registering receivers, the signed payload shape, HMAC verification, and secret rotation.

A webhook is a delivery target: an HTTPS endpoint you own, an HTTP method, optional custom headers, a default payload, and a signing secret.

Register a receiver

curl -X POST https://api.recurrence.cloud/api/v1/webhooks \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourcompany.dev/jobs",
    "method": "POST",
    "secret": "<long random string>",
    "timeoutMs": 30000,
    "appId": "<app id>"
  }'

Options: method (GET|POST|PUT|PATCH|DELETE, default POST), headers (static key/values merged into every delivery), payload (default fields merged under the batch), timeoutMs (1s–300s, default 30s), environmentId.

What actually arrives

One batched delivery, POSTing JSON:

{
  "events": [
    { "id": "evt_01", "subject": "digest-prod", "scheduleId": "…",
      "scheduleName": "morning-digest", "data": { "window": "overnight" } }
  ],
  "organizationId": "org_…",
  "appId": "app_…",
  "webhookId": "wh_…",
  "batchId": "bat_01",
  "attempt": 1,
  "firedAt": "2026-01-01T11:00:00.500Z"
}

Plus these headers:

Header Meaning
X-Organization-Id Owning organization
X-App-Id Owning app
X-Webhook-Id Which registered target
X-Recurrence-Attempt 1 = first fire, 2+ = retry
X-Recurrence-Batch-Id Stable id for this delivery chain
X-Webhook-Signature Hex HMAC-SHA256 over the raw body
X-Signature-Algorithm Always sha256

When several events share a subject on one fire, they arrive grouped:

{
  "subject": "billing-run-01",
  "count": 3,
  "events": [
    { "id": "evt_…", "data": { … } },
    …
  ]
}

Verify before you trust

Signature first — always. Any endpoint that triggers work and skips verification is a remote trigger anyone can fire.

// Next.js / Cloudflare Worker / Deno — Web Crypto, zero dependencies
export async function POST(request: Request) {
  const raw = await request.text();
  const sig = request.headers.get("X-Webhook-Signature");
  if (!sig || !(await verify(raw, sig, process.env.WEBHOOK_SECRET))) {
    return new Response("invalid signature", { status: 401 });
  }
  const batch = JSON.parse(raw);
  // process batch.events (expand grouped { subject, count, events } shapes)
  return new Response("ok");
}

async function verify(raw: string, sigHex: string, secret: string) {
  const key = await crypto.subtle.importKey("raw",
    new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const digest = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw));
  const hex = [...new Uint8Array(digest)].map(b => b.toString(16).padStart(2, "0")).join("");
  return hex === sigHex;
}

Receiver-side checklist:

  1. Verify the signature before parsing into domain objects.
  2. Dedup on identity, not time — retries reuse batchId; key idempotency on (batchId) (+ event ids).
  3. Return fast — a 2xx acknowledges the attempt; fan long work into a queue.
  4. Treat attempts — X-Recurrence-Attempt > 1 means a previous try didn’t 2xx.

Rotate & test without waiting

  • POST /api/webhooks/:id/rotate-secret — new secret for future deliveries; update your receiver, then rotate. URLs never change.
  • POST /api/webhooks/:id/test — fire a probe delivery now and inspect its activity entry.
  • Sign/verify helper endpoints for local tooling: POST /api/api-keys/sign ({key, payload} → signature) and POST /api/api-keys/verify.

Next: Events & batching — designing a series of events as one unit of work.