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:
- Verify the signature before parsing into domain objects.
- Dedup on identity, not time — retries reuse
batchId; key idempotency on(batchId)(+ event ids). - Return fast — a 2xx acknowledges the attempt; fan long work into a queue.
- Treat attempts —
X-Recurrence-Attempt > 1means 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) andPOST /api/api-keys/verify.
Next: Events & batching — designing a series of events as one unit of work.