Skip to main content
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:
Each event’s full payload schema lives in the Webhooks group of the API Reference. 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:
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.
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.