Webhooks

Register an HTTPS endpoint and Sanaa sends it a signed POST when something happens. Events carry identifiers and times only, never a caller's name or number: fetch details from the API.

Events

  • call.started A call began
  • call.ended A call finished: duration, billable minutes, outcome
  • booking.created Sanaa confirmed a booking
  • booking.rescheduled Sanaa moved a booking
  • booking.cancelled Sanaa cancelled a booking
  • transfer.requested A caller asked for a person
  • waitlist.added A caller joined the waitlist
  • tenant.provisioned A tenant's receptionist was created or refreshed
An event
{
  "id": "evt_9f2c...",
  "type": "booking.created",
  "api_version": "2026-11-14",
  "created": 1794700000,
  "data": { "tenant_id": "...", "external_id": "customer_1042", "call_id": "...", "booking_id": "...", "starts_at": "2026-11-17T16:00:00.000Z" }
}

Verify the signature

Every delivery has Sanaa-Timestamp (unix seconds) and Sanaa-Signature (v1= followed by the hex HMAC-SHA256 of "timestamp.rawBody" with your endpoint's secret). Use the raw request body, compare in constant time, and reject timestamps more than 5 minutes old.

TypeScript (Node)
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(secret: string, rawBody: string, signature: string | null, timestamp: string | null): boolean {
  if (!signature || !timestamp) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'v1=' + createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
  const a = Buffer.from(signature), b = Buffer.from(expected)
  return a.length === b.length && timingSafeEqual(a, b)
}
Python
import hmac, hashlib, time

def verify(secret: str, raw_body: bytes, signature: str, timestamp: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, "v1=" + mac)

Responses, retries and replay

Answer with any 2xx to accept an event. Timeouts, network errors, 5xx, 408 and 429 are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then daily, up to 8 attempts. Other 4xx answers are treated as final. Deliveries time out after 10 seconds. Each event has a stable Sanaa-Event-Id header: use it to ignore repeats. The delivery log shows every attempt, and POST /api/v1/webhook_deliveries/{id}/replay sends an event again.

Back to the documentation.