Webhooks: being told the moment something happens

A webhook endpoint is an HTTPS address on your server that ClientTurn POSTs to whenever an event you subscribed to happens. To add one, follow Setting up a webhook.

The request

Every delivery is a POST with a JSON body and these headers:

The body is always the same envelope:

{
  "id": "4f0c…",
  "type": "meeting.booked",
  "created_at": "2026-09-26T09:14:03.120Z",
  "data": { … }
}

Verify the signature

The signature is an HMAC-SHA256, using your endpoint's signing secret, of the timestamp, a full stop, and the raw request body. A Node.js example:

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

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  if (!header) return false;
  let t = null;
  const candidates = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") candidates.push(value);
  }
  if (!Number.isFinite(t) || candidates.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;

  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"),
  );
  return candidates.some((candidate) => {
    const offered = Buffer.from(candidate);
    return offered.length === expected.length && timingSafeEqual(offered, expected);
  });
}

The event catalogue

An event appears here only if ClientTurn actually sends it.

What data contains

For the events delivered through ClientTurn's event outbox, data also carries subject_type, subject_id and occurred_at.

The Test button sends a separate event type, endpoint.test, never a fake lead.created, so your handler can tell a drill from the real thing.

Handling duplicates

Use the event id (also in clientturn-event-id) to make your handler idempotent. It is the same on every retry, and the same event is never queued twice for one endpoint.

Retries and failures

• Answer with any 2xx within 10 seconds to acknowledge.
• A failed delivery is retried up to six more times, after 30 seconds, 5 minutes, 30 minutes, 2 hours, 8 hours and 12 hours: seven attempts in all, over about 22.6 hours. While it is waiting for the next attempt, the delivery shows Retrying. After the last attempt it is marked Gave up.
• A 4xx answer is not retried, except 408 and 429, because repeating a request your server rejected will not change the answer.
• Redirects are not followed. Point the endpoint at the final address.
• After 20 failed deliveries in a row, the endpoint is switched off automatically and marked Disabled, with the reason. Fix the problem and switch it back on.

The Recent deliveries log under your endpoints shows each delivery's status (Queued, Retrying, Delivered, Gave up or Cancelled), what was sent, what your server answered and when the next attempt is due. Your own software can read the same log with GET /api/v1/events.

The signing secret

The secret starts whsec_ and is shown once, when you create the endpoint and when you rotate it. Rotating takes effect immediately with no overlap, so update your server at the same time.

Related

• Setting up a webhook
• API overview and authentication

Screenshots