Webhooks

​

Which requests are signed

​

Get the secret

from unpod import Client

with Client() as client:
    s = client.telephony.webhook_secret.rotate()  # org owner or editor only
    print(s.version, s.pushed_to_sbc)  # False: still syncing, Unpod retries it
    print(s.secret)  # full secret, shown only here: store as UNPOD_WEBHOOK_SECRET

    print(client.telephony.webhook_secret.get().secret)  # masked, e.g. '****ab12'

​

Verify and parse

import os

from fastapi import FastAPI, HTTPException, Request
from unpod.telephony import WebhookSignatureError, parse_call_event

SECRET = os.environ["UNPOD_WEBHOOK_SECRET"]
app = FastAPI()
seen: set[str] = set()


@app.post("/call-status")
async def call_status(request: Request):
    body = await request.body()
    try:
        ev = parse_call_event(body, request.headers, secret=SECRET)
    except WebhookSignatureError:
        raise HTTPException(401)  # unsigned, wrong secret, or older than 300 s

    if ev.event_id:  # the same event can arrive more than once
        if ev.event_id in seen:
            return {"ok": True}
        seen.add(ev.event_id)

    if ev.event == "Answered":
        print(ev.call_id, ev.leg_id, ev.role, "answered")
    elif ev.event == "Hangup":
        print(ev.hangup_cause, ev.sip_code, ev.duration)
    return {"ok": True}  # any 2xx acknowledges

• Pass the raw body exactly as received. Re-encoding it breaks the signature.
• Content-Type decides form or JSON; parse_call_event reads both.
• The same event can arrive more than once (see Delivery and retries). De-duplicate on ev.event_id, and pass an idempotency_key when an event triggers add_participant.
• Return 2xx for events you don’t need, so they aren’t retried.
• tolerance (default 300 s) rejects replays. verify=False skips the check: use it only for local tests and for the unsigned requests.

​

Delivery and retries

• Events for one leg arrive in order (ev.sequence). While one is being retried, that leg’s later events wait behind it; other legs aren’t held up.
• An event queued before you call rotate() is retried signed with the old key, so a server that already has the new key rejects it.
• Return 2xx fast and do slow work afterwards. A reply slower than 10 s is a failure.
• Make handlers idempotent: the same ev.event_id can arrive twice, for example when your 2xx is lost.
• A lost Answered or Hangup can leave someone on the line. As a backstop, sweep your active calls with calls.list() every few minutes, walking every page until one comes back empty, and end any that should be over.
• Answer-URL requests aren’t retried: a failed StartApp applies the fallback, and Hangup and RecordStop are sent once.

​

Events

​

CallEvent fields

​

Hangup causes