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.startedA call begancall.endedA call finished: duration, billable minutes, outcomebooking.createdSanaa confirmed a bookingbooking.rescheduledSanaa moved a bookingbooking.cancelledSanaa cancelled a bookingtransfer.requestedA caller asked for a personwaitlist.addedA caller joined the waitlisttenant.provisionedA tenant's receptionist was created or refreshed
{
"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.
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)
}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.