Webhooks

curl -X POST https://dashboard.zoxa.ai/api/v1/call \
  -H "X-API-Key: zsk_..." \
  -d '{
    "type": "outbound",
    "callConfig": { ... },
    "toNumber": "+1...",
    "agent": {
      "name": "Webhook demo",
      "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
      "systemPrompt": "...",
      "webhook": { "url": "https://your-server.com/webhooks/zoxa" },
      "enableSummarization": true
    }
  }'

{
  "event": "call.started",
  "callId": "call_a1b2c3d4e5",
  "agentId": "ag_f6g7h8i9j0",
  "transport": "web",
  "startedAt": "2026-01-15T14:30:00.000000+00:00"
}

{
  "event": "call.ended",
  "callId": "call_a1b2c3d4e5",
  "agentId": "ag_f6g7h8i9j0",
  "endedReason": "user_hangup",
  "connectionStatus": "completed",
  "duration": 127.45,
  "endedAt": "2026-01-15T14:32:07.450000+00:00"
}

{
  "event": "call.completed",
  "callId": "call_a1b2c3d4e5",
  "agentId": "ag_f6g7h8i9j0",
  "endedReason": "user_hangup",
  "connectionStatus": "completed",
  "duration": 127.45,
  "recordingUrl": "https://cdn.webrexstudio.com/zoxaAI/recordings/call_a1b2c3d4e5.wav",
  "transcript": [
    {"role": "assistant", "content": "Hello! How can I help you today?", "timestamp": "2026-01-15T14:30:00.000+00:00"},
    {"role": "user", "content": "I need to reschedule my appointment.", "timestamp": "2026-01-15T14:30:04.210+00:00"},
    {"role": "assistant", "content": "Of course. What date works for you?", "timestamp": "2026-01-15T14:30:06.840+00:00"},
    {"role": "user", "content": "Next Thursday at 2 PM.", "timestamp": "2026-01-15T14:30:11.115+00:00"},
    {"role": "tool", "name": "updateAppointment", "status": "success", "durationMs": 412, "t_ms": 13800, "timestamp": "2026-01-15T14:30:13.800+00:00"},
    {"role": "assistant", "content": "Done! Your appointment is rescheduled to Thursday at 2 PM. Anything else?", "timestamp": "2026-01-15T14:30:14.600+00:00"},
    {"role": "user", "content": "No, that's all. Thanks!", "timestamp": "2026-01-15T14:30:21.300+00:00"}
  ],
  "transcriptUrl": "https://cdn.webrexstudio.com/zoxaAI/transcripts/call_a1b2c3d4e5.json",
  "summary": "The user called to reschedule an appointment. The agent confirmed the new date as next Thursday at 2 PM. The call ended after the user confirmed no further needs.",
  "usage": {
    "llm": {
      "provider": "openai",
      "model": "gpt-4.1",
      "prompt_tokens": 1250,
      "completion_tokens": 340
    },
    "tts": {
      "provider": "elevenlabs",
      "model": "eleven_flash_v2_5",
      "characters": 412
    },
    "stt": {
      "provider": "soniox",
      "model": "stt-rt-v5",
      "seconds": 127.45
    }
  }
}

{
  "event": "call.transfer_recording.completed",
  "callId": "call_a1b2c3d4e5",
  "agentId": "agent-uuid-or-null",
  "recordingUrl": "https://cdn.example.com/zoxaAI/transfer_recordings/call_a1b2c3d4e5.mp3",
  "durationSeconds": 184.0,
  "telephonyProvider": "twilio",
  "transfer": {
    "transferId": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5b1a7c40",
    "destination": "+15551234567",
    "carrierCallId": "CA9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
  }
}

{
  "event": "call.transfer_recording.failed",
  "callId": "call_a1b2c3d4e5",
  "agentId": "agent-uuid-or-null",
  "reason": "no_recording",
  "telephonyProvider": "twilio",
  "transfer": {
    "transferId": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5b1a7c40",
    "destination": "+15551234567",
    "carrierCallId": "CA9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
  }
}

import hashlib
import hmac

def verify_webhook(request_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        request_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

from fastapi import FastAPI, Request, Header
import hashlib, hmac

app = FastAPI()
WEBHOOK_SECRET = "your-webhook-secret"

@app.post("/webhooks/zoxa")
async def handle_webhook(
    request: Request,
    x_zoxa_signature: str = Header(None),
):
    body = await request.body()

    # Verify signature
    if WEBHOOK_SECRET and x_zoxa_signature:
        expected = hmac.new(
            WEBHOOK_SECRET.encode(), body, hashlib.sha256
        ).hexdigest()
        if not hmac.compare_digest(expected, x_zoxa_signature):
            return {"error": "invalid signature"}, 401

    payload = await request.json()
    event = payload["event"]
    call_id = payload["callId"]

    if event == "call.started":
        print(f"Call {call_id} started via {payload['transport']}")
    elif event == "call.ended":
        print(f"Call {call_id} ended: {payload['endedReason']} ({payload['duration']}s)")
    elif event == "call.completed":
        print(f"Call {call_id} completed with {len(payload.get('transcript') or [])} messages")
        if payload.get("summary"):
            print(f"Summary: {payload['summary']}")

    return {"ok": True}

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = 'your-webhook-secret';

app.post('/webhooks/zoxa', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-zoxa-signature'];

  // Verify signature
  if (WEBHOOK_SECRET && signature) {
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
      return res.status(401).json({ error: 'invalid signature' });
    }
  }

  const payload = JSON.parse(req.body);
  console.log(`Event: ${payload.event}, Call: ${payload.callId}`);

  res.json({ ok: true });
});

app.listen(3000);