Handle call status callbacks

Voicecall status webhooks

Receive ordered webhooks for initiated, ringing, answered, and completed call states, keyed by call ID.

webhooksobservability

The claim

Storing each callback under its CallSid by SequenceNumber rebuilds an ordered timeline of the call, whatever order the callbacks arrived in. The compat call create takes StatusCallback and StatusCallbackEvent, and the vendored spec describes the events as “Valid values: initiated, ringing, answered, completed, ringing_forwarded, ringing_queued. Defaults to completed”. With a StatusCallback and no event list, you ask for only the completed event. This recipe asks for four of the six; ringing_forwarded and ringing_queued are the two it leaves out. The spec documents the payload it posts. The voice status callback carries CallSid, CallStatus, SequenceNumber, Timestamp, Direction, From, To and a block of audio statistics. CallDuration is “Only present on the completed event”, and the spec does not require it there.

Why it holds

SequenceNumber is “The order in which events occur, starting at 0”, and the spec adds that events “may not appear” in that order at your server. So the handler stores by sequence and never by arrival.

How it works

EVENTS = ["initiated", "ringing", "answered", "completed"]

def place(to):
    return client.compat.calls.create(To=to, From=FROM, Url=CALL_URL,
                                      StatusCallback=STATUS_URL,
                                      StatusCallbackEvent=EVENTS,
                                      StatusCallbackMethod="POST")

def record(payload):
    CALLS.setdefault(payload["CallSid"], {})[int(payload["SequenceNumber"])] = payload

What the platform receives:

POST /api/laml/2010-04-01/Accounts/<project>/Calls
{"To": "+1555XXXXXXX", "From": "+1555YYYYYYY", "Url": "https://<your-host>/cxml/greeting.xml",
 "StatusCallback": "https://<your-host>/status",
 "StatusCallbackEvent": ["initiated", "ringing", "answered", "completed"],
 "StatusCallbackMethod": "POST"}

timeline(call_sid) sorts the stored payloads by sequence and returns the steps, the final status, the parties, and the duration when the completed callback carries CallDuration. GET /calls/<CallSid> serves it from the process that holds the store. The fixture’s third callback uses CallStatus in-progress, which the spec’s enum defines as “The call was answered and is in progress”.

Limitations

The spec calls status callbacks “advisory, best-effort notifications” whose “delivery can be delayed or fail silently”. It says not to gate time-critical actions on receiving one. A timeline is a record, not a trigger.

The store is a dictionary in the process. Swap CALLS for your database before anything depends on it.

What to change first

Swap CALLS for a store of your own keyed by CallSid and SequenceNumber, so a restart or a second worker keeps the same ordering. To see what that key protects, as an exercise and not a change to keep: replace int(payload["SequenceNumber"]) in record with len(CALLS[payload["CallSid"]]) and run the verifier. The step-order assertion fails on the fixture’s shuffled arrival, which is the failure this recipe exists to prevent.

Where this sits

Reconcile webhooks against the Logs API Check consent before an outbound call

python/app.py

"""Handle call status callbacks.

Ask for the stages you want and SignalWire posts them to your URL as they
happen, best effort.
The vendored compat spec documents `StatusCallbackEvent` with "Valid values:
initiated, ringing, answered, completed, ringing_forwarded, ringing_queued.
Defaults to `completed`". This recipe asks for the first four. The spec also
documents the payload it posts: `CallSid`, `CallStatus`, `SequenceNumber`
("The order in which events occur, starting at 0"), `Timestamp`, `Direction`,
`From` and `To`. `CallDuration` is "Only present on the `completed` event".

The handler keys payloads by `CallSid` and orders them by `SequenceNumber`,
because the spec says events "may not appear" in order. `timeline()` rebuilds
the call from what arrived.

Written against signalwire-sdk 3.0.1 (RestClient.compat.calls) and Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()

FROM = os.getenv("CALL_FROM")
CALL_URL = os.getenv("CALL_URL")
STATUS_URL = os.getenv("STATUS_CALLBACK_URL")
for name, value in (("CALL_FROM", FROM), ("CALL_URL", CALL_URL),
                    ("STATUS_CALLBACK_URL", STATUS_URL)):
    if not value:
        raise SystemExit(f"{name} is required; see .env.example")

# four of the six documented events, not the default of completed alone
EVENTS = ["initiated", "ringing", "answered", "completed"]

# CallSid -> {SequenceNumber: payload}; swap for your database
CALLS = {}


def place(to):
    """An outbound call that asks for the four stages in EVENTS at STATUS_URL."""
    return client.compat.calls.create(To=to, From=FROM, Url=CALL_URL,
                                      StatusCallback=STATUS_URL,
                                      StatusCallbackEvent=EVENTS,
                                      StatusCallbackMethod="POST")


def record(payload):
    """Store one callback under its call, keyed by sequence so order of arrival
    does not matter."""
    CALLS.setdefault(payload["CallSid"], {})[int(payload["SequenceNumber"])] = payload


def timeline(call_sid):
    """The call's life, rebuilt from whatever callbacks arrived."""
    events = CALLS.get(call_sid, {})
    ordered = [events[n] for n in sorted(events)]
    last = ordered[-1] if ordered else {}
    return {
        "call_sid": call_sid,
        "direction": last.get("Direction"),
        "from": last.get("From"),
        "to": last.get("To"),
        "steps": [{"seq": int(e["SequenceNumber"]), "status": e["CallStatus"],
                   "at": e["Timestamp"]} for e in ordered],
        "final": last.get("CallStatus"),
        "duration": int(last["CallDuration"]) if "CallDuration" in last else None,
    }


app = Flask(__name__)


@app.post("/status")
def status():
    # the spec documents the payload as JSON; a form-encoded post carries the
    # same field names, so the handler accepts both
    record(request.get_json(silent=True) or request.form.to_dict())
    return "", 204


@app.get("/calls/<call_sid>")
def life(call_sid):
    """The timeline. The process that holds the store serves it."""
    return jsonify(timeline(call_sid))


if __name__ == "__main__":
    import sys

    if len(sys.argv) > 1:
        print(place(sys.argv[1]))
    else:
        app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: credentials, CALL_FROM, CALL_URL, STATUS_CALLBACK_URL
python app.py                    # the handler, on port 8080

cd python                        # in another shell
python app.py +1XXXXXXXXXX       # place a call

The handler needs a public HTTPS URL. For a local run, expose port 8080 with a tunnel such as ngrok, and set STATUS_CALLBACK_URL to https://<your-host>/status. CALL_URL is what the spec calls “The URL to handle the call”. Set it to a URL that answers with valid cXML. Then read the life of the call from the running server:

curl "https://YOUR_HOST/calls/CALL_SID"

Verify it

No network, no account.

cd ..                     # back to the recipe folder
python verify.py

The verifier swaps the SDK’s HTTP layer for a recorder and drives the Flask app with its test client. It asserts the following.

place makes one POST to the documented compat calls path with exactly the expected body
the four events it asks for are in the list the spec’s description calls valid, and the two it leaves out are ringing_forwarded and ringing_queued
the callback method is in the spec’s enum
each of four fixture callbacks carries every field the spec’s voice status callback requires, no field it lacks, and a CallStatus from its enum
the spec says CallDuration is only on the completed event and SequenceNumber starts at 0
the four arrive in the order 3, 0, 2, 1, one of them form-encoded, and the handler answers each with 204
the timeline is initiated, ringing, in-progress, completed in sequence order, with the duration from the completed event and the parties from the payload
all 24 arrival orders of the four callbacks give that same complete timeline, compared whole against one expected object
a call with one initiated event has no duration yet, and an unknown call has an empty timeline
a completed callback without CallDuration ends the timeline with completed and no duration
GET /calls/<CallSid> on the server returns the same timeline as JSON

Report an issue