Building calls

Webhooks

SautiPBX talks to your server with two kinds of webhook: call-control webhooks ask your server what to do with a live call and expect a verb document back; status callbacks notify you after the fact that something happened. Both are HTTP POSTs, and both are signed so you can trust they came from us.

The three webhook routes

Every webhook belongs to one purpose. You can point each purpose at a different URL, or send them all to one endpoint and branch on the body.

Call-control: the request we send

When a call needs handling we send an HTTP POST with a JSON body and two signature headers:

POST /handle-call HTTP/1.1
Content-Type: application/json
X-Voice-Signature: <base64 HMAC-SHA256>
X-Voice-Timestamp: 1719900000

{
  "CallSid":    "call_...",
  "AccountSid": "your-account-uuid",
  "Direction":  "outbound",
  "From":       "+254709080010",
  "To":         "+254711111111",
  "CallStatus": "in-progress",
  "customPayload": "{\"orderId\":\"A-42\"}",
  "endUser": {
    "uuid":             "enduser-uuid",
    "email":            "agent@your-app.com",
    "display_name":     "Agent Smith",
    "extension_number": "1010"
  }
}

Respond with 200 OK and your verb document within 10 seconds. Any other status, a timeout, or invalid XML triggers the fallback.

Call-control: action callbacks

Some verbs come back to your server mid-call to ask what to do next. When one does, we POST to its action URL (or, for <Redirect>, the redirect target) with all the fields above plus a few extras describing what just happened. You reply with the next verb document, exactly as with the first request.

<Dial action="..."> — posted when the dialled leg ends:

<Record action="..."> — posted when recording finishes:

<Redirect> re-posts the base call fields with no extras — it simply asks a different URL for the next document.

Status callbacks

A status callback fires for every step of a call's life so you can track it without polling. We POST the same event envelope you see on the event stream, plus two fields the socket omits — id (for de-duplicating retries) and accountId:

POST /call-events HTTP/1.1
Content-Type: application/json
X-Voice-Signature: <base64 HMAC-SHA256>
X-Voice-Timestamp: 1719900000
X-Voice-Event: call.completed

{
  "id":         "a1b2c3d4...",          // unique per event — dedup on this
  "accountId":  "your-account-uuid",
  "code":       "CALL.0300",           // stable machine code — switch on this
  "event":      "call.completed",
  "sid":        "call_...",
  "customPayload": { "caseId": "CASE-0042" },  // present only if you set one
  "createdAt":  "2026-07-05T10:00:00Z",
  "data": {
    "sid":              "call_...",
    "direction":        "inbound",
    "from_number":      "+254711111111",
    "to_number":        "+254709080010",
    "status":           "completed",
    "reason_code":      "END.0200",
    "duration_seconds": 42,
    "talk_seconds":     37,
    "started_at":       "2026-07-05T09:59:18Z",
    "answered_at":      "2026-07-05T09:59:23Z",
    "ended_at":         "2026-07-05T10:00:00Z"
  }
}

Which lifecycle events map to which codes (call.initiated → CALL.0100, call.answered → CALL.0200, and so on) is listed in full under Events & codes. The same catalogue is used by the stream, so a webhook consumer and a socket consumer see one contract.

Delivery & retries

Status callbacks are delivered with automatic retries. We treat any 2xx as success; anything else (or a timeout) is retried on this schedule:

• A successful delivery emits a webhook.delivered (WH.0200) event.
• If all retries fail, we emit a webhook.failed (WH.0400) event and increment the endpoint's failure counter.
• After 5 consecutive failed deliveries, the route is auto-disabled and you're notified. A single successful delivery resets the counter. Re-enable a disabled route from the portal's Webhooks page.

Because retries reuse the same id, always make your handler idempotent: acknowledge fast with 200, then process asynchronously.

Debugging a delivery? The portal's Webhooks page shows every attempt for an endpoint, including the response status and body your server returned — no need to add your own logging to see why a delivery was rejected.

Verify the signature

Every webhook we send — call-control, action callback, or status — is signed the same way. The signature proves the request came from us and was not tampered with. It is computed over URL + timestamp + body using your account's webhook signing secret (find it under Webhooks in the portal, or with GET /account/webhooks/secret).

To verify: take the raw request body exactly as received, prepend the request URL and the X-Voice-Timestamp, HMAC-SHA256 it with your secret, base64-encode, and compare — using a constant-time comparison — against X-Voice-Signature.

import base64, hashlib, hmac, time

def verify(secret, url, raw_body, signature, timestamp):
    # reject anything older than 5 minutes (replay protection)
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = f"{url}{timestamp}".encode() + raw_body
    digest = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()
    return hmac.compare_digest(expected, signature)

Rotating the secret

You have one signing secret per account, shared by all three webhook routes. Rotate it with POST /account/webhooks/secret/rotate — the old secret stops verifying immediately, so roll it out to your servers first.

Configuring URLs

For a given purpose, we resolve which URL to call in this order:

1. A per-call url (for outbound calls, the url you passed to /calls/originate).
2. A per-number URL override, set with POST /numbers/configure.
3. Your account-default URL for that purpose, set with POST /account/webhooks/endpoint.

Each purpose resolves independently — a per-number inbound override never affects your outbound or status routes. Configure all three from Settings → Webhooks & Signing, or set per-DID overrides from the number's configure dialog.

Browser-phone outbound is webhook-required

When a browser-phone end-user places an outbound call, SautiPBX always calls your voice_outbound webhook for a verb document before dialling the PSTN — it never dials on its own. This is the same model as inbound and API-originated calls: call control comes from your <Response> XML.

A minimal outbound webhook that dials the number the user dialled, presenting your DID:

# The call body contains Direction="outbound", From=your DID, To=what the user dialled
def handle_outbound(request):
    body = request.json()
    return f"""<Response>
    <Dial><Number>{body['To']}</Number></Dial>
</Response>"""

Return any verb document — you can screen the call, play an announcement, route to a queue, or reject it before a single second of PSTN time is used.

Fallback

If a call-control webhook cannot be reached or returns something we cannot use, we apply the account fallback so the caller is never left in silence. Set it with POST /account/webhooks:

Whenever a fallback fires, you also receive a webhook.failed event explaining why — see Events & codes. (Status callbacks have no fallback; they retry instead.)