Python SDK webhooks - Telnyx

Telnyx signs every webhook delivery with an ED25519 signature carried in the telnyx-signature-ed25519 and telnyx-timestamp request headers. The SDK’s webhook helper verifies the signature against your account’s public key and parses the payload into a typed event. Webhook verification needs the optional webhooks extra:

pip install "telnyx[webhooks]"

Copy your public key from the Mission Control Portal and expose it as TELNYX_PUBLIC_KEY — the client reads it automatically, the same way it reads TELNYX_API_KEY:

export TELNYX_PUBLIC_KEY="..."

Verify and parse an event

Pass the raw request body and the request headers to client.webhooks.unwrap(). Verification needs the exact bytes Telnyx sent, so read the body directly rather than re-serializing parsed JSON:

from fastapi import FastAPI, Request, Response
from telnyx import Telnyx

client = Telnyx()  # reads TELNYX_API_KEY and TELNYX_PUBLIC_KEY

app = FastAPI()


@app.post("/webhooks/telnyx")
async def telnyx_webhook(request: Request) -> Response:
    payload = (await request.body()).decode("utf-8")
    try:
        event = client.webhooks.unwrap(payload, headers=request.headers)
    except Exception:
        return Response(status_code=400)  # signature invalid or payload malformed
    print(event.data.event_type)
    return Response(status_code=200)

unwrap() raises when the signature does not match, and returns the parsed event as a typed union of every webhook event the API sends — check event.data.event_type to handle specific events.

Skipping verification

client.webhooks.unsafe_unwrap(payload) parses a payload without checking the signature. Only use it for payloads you have already verified by other means, or in tests.

Receiving webhooks covers delivery, retries, and failover URLs.
Errors, retries, and timeouts covers the SDK’s exception hierarchy.

⌘I