Webhooks

Sautikit POSTs signed JSON to your HTTPS endpoint when something happens in your workspace. Delivery is at-least-once: the same event can arrive more than once, so deduplicate on the X-Sautikit-Event-Id header. A failed delivery is tried up to 8 times.

Two kinds of events

Workspace webhooks

Subscribe with POST /v1/webhooks, giving a url and an events array. The response includes the signing secret; it is shown once, so store it.

const res = await fetch("https://api.sautikit.com/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAUTIKIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.example.com/events",
    events: ["wallet.*", "number.*", "call.recording.available"],
  }),
});
const { secret } = await res.json();

These are the events you can subscribe to:

Wildcards in the events array:

• * matches every event in the table.
• wallet.*, number.*, storage.*, broadcast.*, dialer.* and agent.* match a family.
• There is no call.* or whatsapp.* wildcard. List the call.recording.*, call.supervision.* and whatsapp.* events you want by name.

Per-number call events

Call events are sent to the events_url on a number's routing (set it with PUT /v1/numbers/{id}/routing). You cannot subscribe to them as workspace webhooks.

Every call event is a POST with the same flat JSON body. The callSessionState field says where the call is:

Per-number events are POSTed once to your events_url. They are not signed and not retried, and they carry no X-Sautikit-* headers. The headers, signature and retries described below apply to workspace webhooks.

Live transcripts

For a call handled by an AI agent, transcript.turn and transcript.delta arrive on the call's event stream, GET /v1/calls/{id}/stream, and there is no webhook for them. An API key with calls.read can read the stream from your server. The saved transcript is on GET /v1/calls/{id}?transcript=1.

Request headers

Every workspace webhook delivery carries these headers:

Request body

The body is flat JSON: the event's own fields are at the top level, with no wrapper object. A wallet.low_balance delivery looks like this:

{
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "balance_minor": 4800,
  "currency": "KES",
  "threshold": 5000,
  "trigger": "cron_scan"
}

Not every body names its event, so read the event name from the X-Sautikit-Event-Kind header.

Handling a delivery

import express from "express";
// verifyWebhook is the function from the "Verify webhook signatures" guide.
import { verifyWebhook } from "./verify-webhook.js";
 
const app = express();
const seen = new Set(); // use a database or cache in production
 
app.post("/events", express.raw({ type: "application/json" }), (req, res) => {
  try {
    verifyWebhook(req.body, req.get("X-Sautikit-Signature"), process.env.WEBHOOK_SECRET);
  } catch {
    return res.sendStatus(400);
  }
 
  const eventId = req.get("X-Sautikit-Event-Id");
  if (seen.has(eventId)) return res.sendStatus(200);
  seen.add(eventId);
 
  const kind = req.get("X-Sautikit-Event-Kind");
  const event = JSON.parse(req.body);
 
  if (kind === "wallet.low_balance") {
    console.log(`Balance is KES ${event.balance_minor / 100}`);
  }
 
  res.sendStatus(200);
});

Signature verification

The X-Sautikit-Signature header has the format:

t=<unix_timestamp>,v1=<hex_hmac>

The HMAC is:

HMAC-SHA256(key=signing_secret, message=raw_body + "." + timestamp)

• signing_secret is the secret returned when you created the webhook or rotated its secret.
• raw_body is the exact bytes received. Do not parse and re-encode them.
• timestamp is the t= value from the same header.

Reject a delivery whose timestamp is more than 5 minutes from your server clock, to stop replays.

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verifyWebhook(rawBody, sigHeader, secret) {
  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=", 2))
  );
  const ts = parts["t"];
  const v1 = parts["v1"];
  if (!ts || !v1) throw new Error("missing t or v1");
 
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    throw new Error("timestamp too old");
  }
 
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .update(".")
    .update(ts)
    .digest("hex");
 
  const a = Buffer.from(v1);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    throw new Error("signature mismatch");
  }
}

Verify webhook signatures has the same function in Python, Go and PHP, and the common mistakes.

Delivery

Timeout

Respond with any 2xx status within 10 seconds. A response body is not needed. A non-2xx response or a timeout counts as a failed attempt.

Retry schedule

A delivery is attempted up to 8 times. After the 8th failed attempt it is marked dead_letter and not tried again.

Retry a delivery yourself with POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry.

Suspended workspaces

If your workspace is suspended when a delivery is due, the delivery is marked skipped_suspended and is not retried.

Monitoring deliveries

const res = await fetch(
  `https://api.sautikit.com/v1/webhooks/${webhookId}/deliveries`,
  { headers: { Authorization: `Bearer ${process.env.SAUTIKIT_API_KEY}` } }
);

A delivery's status is pending, succeeded, failed (waiting for the next attempt), dead_letter or skipped_suspended.

Send yourself a test delivery with POST /v1/webhooks/{id}/test.

Next steps

• Verify webhook signatures (guide)
• Webhooks API reference
• Call event types