Webhooks

​

Events we deliver

​

Delivery and retries

• A failed delivery is retried up to 20 times with jittered exponential backoff, from 15 seconds up to 6 hours between attempts, so it keeps trying for days until your endpoint answers 2xx.
• The same event may arrive more than once - dedupe on webhook-id (the event id), which is stable across retries.
• Events for one endpoint are delivered in order, best effort: a newer event normally waits until the older ones for that endpoint are acknowledged, so company.created lands before the requirement.created that followed it. That hold is bounded, not absolute - an event that keeps failing is set aside after a few attempts so one bad delivery cannot hold the rest of your events back for days. Deliveries to a single endpoint are also paced: we send one at a time rather than in a burst, so a slow listener is not flooded. Treat order as the normal case, not a guarantee - dedupe on webhook-id and tolerate the occasional reorder. To keep the order honest even for events created at nearly the same instant, a fresh delivery starts a couple of seconds after its event.
• A Retry-After header on a 429 or 503 pushes our next attempt back.
• Answer 410 Gone to unsubscribe: the endpoint is disabled and its queued deliveries are paused.
• An endpoint failing for a while has the workspace owner emailed a warning, and one that fails continuously for three days is then disabled automatically (the owner is emailed again). No events are lost - replay what you missed from GET /events (see Reconciling by polling), and re-enabling the endpoint resumes whatever was queued when it was disabled.
• Redirects are not followed - a 3xx counts as a failure. If your URL moved, update the endpoint.

​

Verifying a delivery

Clemta-Webhook-Id: evt_0346sFPEvSkJvY8vt14NNw
Clemta-Webhook-Timestamp: 1755561600
Clemta-Webhook-Signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1a,fQ3k...signature...Cg==

• Clemta-Webhook-Id is the event id - stable across retries, your idempotency key.
• Clemta-Webhook-Timestamp is the unix time of this attempt (a retry is re-signed fresh, so it stays inside your tolerance window).
• Clemta-Webhook-Signature is a space-delimited list of signatures, each prefixed with its scheme. Skip entries whose prefix you do not verify and match any one that you do:
  • v1, + base64 of HMAC-SHA256(key, "<id>.<timestamp>.<body>"), where the key is your secret base64-decoded after the whsec_ prefix, over the exact raw request body. During a secret rotation there are two v1 entries - old and new secret both verify until the overlap ends.
  • v1a, + base64 of the ed25519 signature over the identical "<id>.<timestamp>.<body>" string, verifiable with the endpoint’s public_key (base64-decoded after the whpk_ prefix). Secret rotations never touch it.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret, toleranceSec = 300) {
  const id = headers["clemta-webhook-id"];
  const t = Number(headers["clemta-webhook-timestamp"]);
  if (!id || !t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${t}.${rawBody}`)
    .digest("base64");
  // During a rotation there can be more than one signature; match any v1.
  return headers["clemta-webhook-signature"]
    .split(" ")
    .filter((p) => p.startsWith("v1,"))
    .map((p) => p.slice(3))
    .some(
      (c) =>
        c.length === expected.length &&
        timingSafeEqual(Buffer.from(c), Buffer.from(expected))
    );
}

​

Verifying without a shared secret (v1a)

import { verify as edVerify, createPublicKey } from "node:crypto";

function verifyAsymmetric(rawBody, headers, publicKey, toleranceSec = 300) {
  const id = headers["clemta-webhook-id"];
  const t = Number(headers["clemta-webhook-timestamp"]);
  if (!id || !t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const raw = Buffer.from(publicKey.replace(/^whpk_/, ""), "base64");
  const key = createPublicKey({
    key: Buffer.concat([
      Buffer.from("302a300506032b6570032100", "hex"), // SPKI header for a raw ed25519 key
      raw,
    ]),
    format: "der",
    type: "spki",
  });
  const message = Buffer.from(`${id}.${t}.${rawBody}`);
  return headers["clemta-webhook-signature"]
    .split(" ")
    .filter((p) => p.startsWith("v1a,"))
    .map((p) => Buffer.from(p.slice(4), "base64"))
    .some((sig) => edVerify(null, message, key, sig));
}

​

Rotating a secret

​

Payload versioning

​

Managing endpoints

• Create an endpoint with its URL. Optionally restrict it to some event types and pin its payloads to an API version. The signing secret is shown once, so store it then.
• Roll its secret - confirmed by email, with the overlap above.
• Disable an endpoint - deliveries stop and queued ones are paused. This is reversible.
• Enable a disabled endpoint again - it keeps its id, secret and signing key, so you need not recreate it, and the deliveries paused when it was disabled resume. A manual disable, a 410, and an automatic disable all re-enable the same way.
• Inspect deliveries for the last 30 days - the exact payload sent, the response body, and each attempt with its result - and retry a single stuck delivery or an endpoint’s whole backlog at once.

​

Reconciling by polling

• A safety net beside webhooks - a periodic sweep that catches anything your endpoint missed (an outage longer than the retry horizon, an endpoint disabled for a while).
• A full replacement for webhooks - if you would rather not run a public endpoint, poll the stream on an interval and you receive everything, pulled instead of pushed.

1. Remember when your last sweep ran.
2. Ask for everything since a few minutes before that: GET /events?created_at[gte]=<last_sweep - 5m>&sort=created_at, following the cursor (after=<end_cursor>) until has_next_page is false.
3. Process each event idempotently, keyed by its id - the same value the webhook-id header carries, so one dedupe set covers both channels.