Webhooks.

curl -X POST https://voice.whizztech.ai/v1/webhooks \
  -H "Authorization: Bearer $WHIZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.your-app.com/hooks/whizz",
    "events": ["call.started", "call.completed", "call.failed"]
  }'

{
  "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
  "object": "webhook_endpoint",
  "url": "https://api.your-app.com/hooks/whizz",
  "events": ["call.started", "call.completed", "call.failed"],
  "secret": "whsec_Zks3JprXcO1FaK9yTqR2v8wBnE5dLmHu"
}

{
  "object": "list",
  "data": [
    {
      "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
      "url": "https://api.your-app.com/hooks/whizz",
      "events": ["call.started", "call.completed", "call.failed"],
      "active": true,
      "created_at": "2026-07-10T10:02:31.000Z"
    }
  ]
}

POST /hooks/whizz HTTP/1.1
Content-Type: application/json
webhook-id: 7c2f4e91-0b5d-4a68-93e1-d8f60a2c47b5
webhook-timestamp: 1783677103
webhook-signature: v1,K6mQxNvB2rTz8wYpL0dHc4jFgS7aEuXiOn9kM3sRq1U=

{
  "event": "call.completed",
  "data": {
    "id": "call_1d84c0e795b2",
    "object": "call",
    "agent_id": "ag_7Q2c51b84a07",
    "direction": "outbound",
    "status": "completed",
    "from": "+966920000123",
    "to": "+966500000001",
    "phone_number_id": "pn_5b8f0d21",
    "channel": "phone",
    "duration_sec": 96,
    "billed_sec": 96,
    "language": "ar",
    "dialect": "saudi",
    "lang_tier": "arabic",
    "outcome": "resolved",
    "sentiment": "positive",
    "recording_url": "https://voice.whizztech.ai/rec/call_1d84c0e795b2.mp3?sig=…",
    "transcript": {
      "segments": [
        { "speaker": "agent", "start": 0.0, "end": 3.1, "text": "حياك الله، معك مساعد وِز. كيف أقدر أخدمك؟" },
        { "speaker": "caller", "start": 3.4, "end": 6.8, "text": "أبغى أعرف حالة طلبي A-2291." },
        { "speaker": "agent", "start": 7.0, "end": 11.2, "text": "طلبك خرج للتوصيل ويوصلك اليوم قبل المغرب." }
      ],
      "language_code": "ar-SA",
      "word_count": 148
    },
    "tool_calls": [
      { "name": "lookup_order", "args": { "order": "A-2291" }, "result": { "status": "out_for_delivery", "eta": "2026-07-13" } }
    ],
    "cost": { "voice_credits": 24, "telephony_usd": 0.024 },
    "error": null,
    "created_at": "2026-07-13T09:32:18.000Z",
    "ended_at": "2026-07-13T09:33:54.000Z"
  }
}

{
  "event": "call.failed",
  "data": {
    "id": "call_7b2e0a9c6543",
    "object": "call",
    "agent_id": "ag_7Q2c51b84a07",
    "direction": "outbound",
    "status": "no_answer",
    "from": "+966920000123",
    "to": "+966500000002",
    "phone_number_id": "pn_5b8f0d21",
    "channel": "phone",
    "duration_sec": 0,
    "billed_sec": 0,
    "outcome": null,
    "sentiment": null,
    "recording_url": null,
    "transcript": null,
    "tool_calls": [],
    "cost": { "voice_credits": 0, "telephony_usd": 0.006 },
    "error": { "code": "no_answer", "message": "Recipient did not answer before ring timeout." },
    "created_at": "2026-07-13T09:34:02.000Z",
    "ended_at": "2026-07-13T09:34:32.000Z"
  }
}

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

/**
 * Verify a Whizz Voice webhook (Standard Webhooks scheme).
 * payload must be the RAW request body string — not re-serialized JSON.
 */
export function verifyWhizzWebhook(payload, headers, secret, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (!id || !timestamp || !signature) return false;

  // reject stale or future-dated deliveries (replay protection)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;

  // key = base64-decoded secret without the whsec_ prefix
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signedContent = id + "." + timestamp + "." + payload;
  const expected =
    "v1," + createHmac("sha256", key).update(signedContent).digest("base64");

  // the header may carry multiple space-delimited signatures; ours sends one
  return signature.split(" ").some((candidate) => {
    const a = Buffer.from(candidate);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

// Express example — mount with express.raw() so the body stays untouched:
// app.post("/hooks/whizz", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyWhizzWebhook(req.body.toString("utf8"), req.headers, process.env.WHIZZ_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const { event, data } = JSON.parse(req.body.toString("utf8"));
//   res.status(200).end(); // ack fast, process async
// });

import base64
import hashlib
import hmac
import time


def verify_whizz_webhook(payload: bytes, headers: dict, secret: str, tolerance_sec: int = 300) -> bool:
    """payload must be the RAW request body bytes — not re-serialized JSON."""
    wid = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    sig = headers.get("webhook-signature")
    if not (wid and ts and sig):
        return False

    # reject stale or future-dated deliveries (replay protection)
    if abs(time.time() - int(ts)) > tolerance_sec:
        return False

    # key = base64-decoded secret without the whsec_ prefix
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed_content = f"{wid}.{ts}.".encode() + payload
    digest = hmac.new(key, signed_content, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()

    # the header may carry multiple space-delimited signatures; ours sends one
    return any(hmac.compare_digest(candidate, expected) for candidate in sig.split(" "))