Webhooks

Delivery

• Body: { "id", "type", "timestamp", "api_version", "org_id", "data" }. id equals the webhook-id header and stays the same on retries and replays: use it to ignore duplicates.
• Answer with any 2xx within 10 seconds. Do slow work after answering. Redirects are not followed.
• Retries after a failure: 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h (with jitter), 8 attempts in total. Then the delivery is marked failed and you can replay it from the dashboard.
• HTTP 410 Gone turns the endpoint off at once; 20 failed deliveries in a row turn it off too. Turning it back on resets the counter.
• Only public HTTPS addresses are called (no private networks, no cloud metadata addresses), and the address is checked again on every delivery.
• Order is not guaranteed. Use timestamp, or fetch the current object from the API.

Verify the signature

We follow Standard Webhooks. Compute HMAC-SHA256 over webhook-id.webhook-timestamp.body with the base64 part of your whsec_ secret, and compare it with each v1, value in webhook-signature. Reject timestamps older than 5 minutes. While you rotate a secret, both the new and the old secret sign each delivery.

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

// Use the RAW request body (before JSON parsing).
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"], sigs = headers["webhook-signature"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error("too old");
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  const ok = sigs.split(" ").some((s) => {
    const got = Buffer.from(s.split(",")[1] ?? "", "base64");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
  if (!ok) throw new Error("bad signature");
  return JSON.parse(rawBody);
}

Event catalogue

Subscribe to exact events, a whole product (lead.*) or everything (*). Also as JSON: /api/v1/events.