Webhooks

curl https://api.kallabot.com/v1/webhooks \
  -H "Authorization: Bearer $KALLABOT_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/webhooks/kallabot",
    "name": "CRM sync",
    "events": ["call.ended", "call.analyzed", "conversation.*"],
    "agent_ids": [],
    "include_content": false
  }'

const endpoint = await kallabot.webhooks.create({
  url: "https://example.com/webhooks/kallabot",
  name: "CRM sync",
  events: ["call.ended", "call.analyzed", "conversation.*"],
});
console.log(endpoint.secret); // whsec_… shown once

endpoint = client.webhooks.create(
    url="https://example.com/webhooks/kallabot",
    name="CRM sync",
    events=["call.ended", "call.analyzed", "conversation.*"],
)
print(endpoint.secret)  # whsec_… shown once

import { Webhooks, WebhookVerificationError } from "@kallabot/sdk";

export async function POST(request: Request) {
  const raw = await request.text(); // the raw body
  try {
    const event = await Webhooks.verify(raw, request.headers, process.env.KALLABOT_WEBHOOK_SECRET!);
    if (event.type === "call.ended") await saveCall(event.data.call_id, event.data.talk_ms);
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response(err.message, { status: 400 });
    throw err;
  }
}

import kallabot
from fastapi import FastAPI, Request, Response
from kallabot.webhooks import CallEndedEvent

app = FastAPI()
client = kallabot.Kallabot()  # reads KALLABOT_WEBHOOK_SECRET too

@app.post("/webhooks/kallabot")
async def kallabot_webhook(request: Request) -> Response:
    try:
        event = client.webhooks.unwrap(await request.body(), request.headers)
    except kallabot.WebhookVerificationError:
        return Response(status_code=400)
    if isinstance(event, CallEndedEvent):
        save_call(event.data.call_id, event.data.talk_ms)
    return Response(status_code=204)

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";
import express from "express";

const wh = new Webhook(process.env.KALLABOT_WEBHOOK_SECRET); // "whsec_…"
const app = express();

app.post("/webhooks/kallabot", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, {
      "webhook-id": req.header("webhook-id"),
      "webhook-timestamp": req.header("webhook-timestamp"),
      "webhook-signature": req.header("webhook-signature"),
    });
  } catch {
    return res.sendStatus(400);
  }
  queue.add(event); // do the work later
  res.sendStatus(204);
});

# pip install standardwebhooks
import os
from fastapi import FastAPI, Request, Response
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["KALLABOT_WEBHOOK_SECRET"])  # "whsec_…"
app = FastAPI()

@app.post("/webhooks/kallabot")
async def kallabot(request: Request):
    body = await request.body()
    try:
        event = wh.verify(body, dict(request.headers))
    except WebhookVerificationError:
        return Response(status_code=400)
    queue.put(event)  # do the work later
    return Response(status_code=204)

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

export function verifyKallabot(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const header = headers["webhook-signature"];
  if (!id || !timestamp || !header) throw new Error("Missing signature headers");

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) throw new Error("Timestamp too old");

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest();

  // During a secret rotation the header holds two signatures, space separated.
  const valid = header.split(" ").some((part) => {
    const [version, signature] = part.split(",");
    if (version !== "v1" || !signature) return false;
    const given = Buffer.from(signature, "base64");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
  if (!valid) throw new Error("Bad signature");
  return JSON.parse(rawBody.toString("utf8"));
}

import base64, hashlib, hmac, json, time

TOLERANCE_SECONDS = 5 * 60

def verify_kallabot(raw_body: bytes, headers, secret: str) -> dict:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    header = headers.get("webhook-signature")
    if not (msg_id and timestamp and header):
        raise ValueError("Missing signature headers")

    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        raise ValueError("Timestamp too old")

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    # During a secret rotation the header holds two signatures, space separated.
    for part in header.split(" "):
        version, _, signature = part.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return json.loads(raw_body)
    raise ValueError("Bad signature")