Reconcile webhooks against the Logs API

Voicewebhook reconciliation against call logs

Page through voice and message logs, find entries missing from your webhook store, and retrieve each missing call's event history.

Also called CDR, call detail records, call logs API

observability

The claim

GET /api/voice/logs and GET /api/messaging/logs take created_after, created_before and page_size in the vendored REST spec. When a page carries links.next, the recipe passes that URL’s query to the same list method. GET /api/voice/logs/{id}/events answers with a data array of event entries. The spec requires event_at, level, name, details, project_id and log_id on each. You reach them as client.logs.voice.list, client.logs.messages.list and client.logs.voice.list_events. You walk both lists to the end, diff them against the ids your handler stored, and every id the store lacks is a candidate to reconcile.

How it works

def every_page(fetch, **params):
    entries, page = [], fetch(**params)
    while True:
        entries.extend(page.get("data", []))
        nxt = (page.get("links") or {}).get("next")
        if not nxt:
            return entries
        page = fetch(**dict(parse_qsl(urlsplit(nxt).query)))

def reconcile(since, until):
    report = {"voice": [], "messages": []}
    for entry in missed(voice_logs(since, until)):
        report["voice"].append({"log": entry, "events": events_for(entry["id"])})
    report["messages"] = missed(message_logs(since, until))
    return report

What the platform receives for one pass over a two-page voice window:

GET /api/voice/logs?created_after=...&created_before=...&page_size=200
GET /api/voice/logs?page_token=...&page_size=200
GET /api/voice/logs/<first unseen id>/events
GET /api/voice/logs/<second unseen id>/events
GET /api/messaging/logs?created_after=...&created_before=...&page_size=200

every_page re-issues the query string each links.next carries, so it follows whatever pagination the platform hands back. SEEN stands in for whatever your webhook handler writes: a table of voice and message ids. Keep it per product, so an id that appears in both cannot hide an entry. An id in the window that your table lacks is an entry you have no record of. Why you have none is for you to work out, and the events trail is where you start.

Limitations

The diff is by id: the pass compares each log entry’s id with the ids your handler stored. Neither callback document in the vendored specs states that its id equals the log entry’s id. Check both mappings against your own account before trusting the report.

You prove the requests and the diff against fixtures; what the logs contain for a real window is the platform’s record.

A log entry’s fields depend on its type. The spec’s voice log is a oneOf over Relay, Fabric, video room, Dialogflow and discarded shapes, and all of them carry id.

What to change first

Replace the body of every_page with return fetch(**params).get("data", []) and run the verifier. The request sequence fails because the pass never fetches a second page, and the report loses the voice log and the message that sat on one. A window is every page, not the first one.

Where this sits

Before this

Send an SMS

Place an outbound call

python/app.py

"""Reconcile webhooks against the logs API.

Your host can miss a status webhook: it was down, a proxy timed out, a deploy
was mid-flight. The voice and message logs list what the platform recorded. A
scheduled pass over a time window walks every page of both lists and reports
every entry your handler's store lacks, as candidates to reconcile.
`GET /api/voice/logs` and `GET /api/messaging/logs` take `created_after` and
`created_before`. Each voice log's events are one more GET away.

Written against signalwire-sdk 3.0.1 (RestClient.logs).
"""
from urllib.parse import parse_qsl, urlsplit

from dotenv import load_dotenv
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()

# What your webhook handler recorded, one set per product so a voice id and a
# message id that happen to match cannot hide each other. A real one is a
# table; the reconciler only needs membership.
SEEN = {"voice": set(), "messages": set()}


def every_page(fetch, **params):
    """Walk a list to its end. Each page's `links.next` is a URL whose query
    carries the next page's parameters, so the walk re-issues the query the URL
    supplies. The spec's page_size maximum is 1000."""
    entries = []
    page = fetch(**params)
    while True:
        entries.extend(page.get("data", []))
        nxt = (page.get("links") or {}).get("next")
        if not nxt:
            return entries
        page = fetch(**dict(parse_qsl(urlsplit(nxt).query)))


def voice_logs(since, until, page_size=200):
    """Every voice log the platform kept for the window, all pages."""
    return every_page(client.logs.voice.list, created_after=since,
                      created_before=until, page_size=page_size)


def message_logs(since, until, page_size=200):
    """Every message log for the window, all pages."""
    return every_page(client.logs.messages.list, created_after=since,
                      created_before=until, page_size=page_size)


def missed(entries, product):
    """Entries your store lacks for this product: the candidates to reconcile."""
    return [entry for entry in entries if entry.get("id") not in SEEN[product]]


def events_for(log_id):
    """The event trail of one voice log, for the ones you missed."""
    return client.logs.voice.list_events(log_id)


def reconcile(since, until):
    """One pass: list the window, diff against what you saw, fetch the trail
    of each missed call."""
    report = {"voice": [], "messages": []}
    for entry in missed(voice_logs(since, until), "voice"):
        report["voice"].append({"log": entry, "events": events_for(entry["id"])})
    report["messages"] = missed(message_logs(since, until), "messages")
    return report


if __name__ == "__main__":
    import json
    import sys

    if len(sys.argv) != 3:
        raise SystemExit("usage: python app.py <since ISO-8601> <until ISO-8601>")
    print(json.dumps(reconcile(sys.argv[1], sys.argv[2]), indent=1))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: your project id, API token and space
python app.py 2026-09-01T00:00:00Z 2026-09-02T00:00:00Z

There is no server to expose; the script speaks to the REST API and exits. Replace SEEN with a lookup into wherever your webhook handler records ids. With it empty, the report lists every entry in the window.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

You swap the SDK’s HTTP layer for a recorder that answers with fixtures. They are two voice pages, two message pages, and a trail per unseen call. In each list, page one’s links.next URL points at page two. You run a pass and assert the following.

the pass makes seven requests in order: voice page one, voice page two, one events request per unseen voice log, message page one, message page two
page one of each list carries the window parameters, and page two of each carries exactly the query from its links.next URL
the events requests carry no query, and each event in a trail carries every field the spec requires
the spec documents every path and parameter used
the report equals one expected object. It holds the three unseen voice logs whole, each with its own trail, the two unseen messages whole, and nothing the store holds
judge a shared id within its product: the store holds the message id, so the pass excludes the message and reports the voice log
one of the calls and one of the messages come from a second page
the spec bounds page_size at exactly 1 and 1000 on both lists

Report an issue