Webhooks

Receive meeting session events on your own endpoint and verify their signatures.

Instead of polling, point the bot at your own endpoint. Set webhook_url when creating the session and Telnyx pushes session events to it. The destination must be a public HTTPS URL without embedded credentials and must not resolve to loopback, private, link-local, or otherwise reserved addresses; redirects are not followed. Each session returns a webhook_secret exactly once at creation — store it; it is not retrievable again.

Envelope and Events

Every delivery is an HTTP POST with Content-Type: application/json, no authorization header, and one envelope shape — deduplicate on id:

{
  "id": "whdel_9f2c...",
  "event": "session.status_changed",
  "version": "1",
  "occurred_at": "2026-06-16T09:00:05Z",
  "data": {}
}

Event	data fields
session.status_changed	session_id, status, status_detail, recording
transcript.completed	session_id, segment_count, last_seq, ended_at
artifact.completed	session_id, artifact_id, type, prompt (the question a custom artifact answered, null for a named type), content: {text}, model_provenance
artifact.failed	session_id, artifact_id, type

Each event’s full payload schema lives in the Webhooks group of the API Reference. New event types can be added, so acknowledge any event value you do not recognize with a 2xx and ignore it. Individual transcript.segment messages are never delivered over webhooks. Read segments via the transcript endpoint or the stream.

Verify Signatures

Each delivery is signed with an X-Meeting-Bot-Signature header:

X-Meeting-Bot-Signature: t=1784297100,v1=5e8f...a3c1

Compute HMAC-SHA256 over the timestamp’s ASCII bytes, a literal . byte, and the exact raw request-body bytes, then hex-encode the result and compare it against v1. Do not parse and reserialize the JSON before verifying.

import hashlib
import hmac

header = "t=1784297100,v1=5e8f...a3c1"
raw_body = request.body  # exact bytes as received

t = header.split(",")[0].split("=")[1]
v1 = header.split(",")[1].split("=")[1]

expected = hmac.new(
    webhook_secret.encode(),
    t.encode() + b"." + raw_body,
    hashlib.sha256,
).hexdigest()

verified = hmac.compare_digest(v1, expected)

Concatenate the timestamp and body as bytes. Formatting raw_body into a string (for example with an f-string) produces b'...' in the signed payload and the comparison always fails.

Use a constant-time comparison and reject deliveries whose timestamp is outside your accepted clock skew window.

Delivery and Retry

• Up to 5 delivery attempts. Non-2xx responses, redirects, network errors, and timeouts all consume an attempt.
• Retries back off: roughly a minute after the first failed attempt, doubling each retry (about 60s * 2^n).
• Each attempt has a 10-second timeout, so respond with a 2xx promptly.
• Events are delivered with best effort and duplicates can occur — including when your endpoint processed an event but its response was lost. Deduplicate on the event id and fall back to REST polling when guaranteed receipt matters.

Related

• Session Events — the full event history, and what to read when a delivery is missed
• Join a Meeting — set webhook_url when creating a session
• Collect Results — read the finalized transcript and artifacts