Skip to main content
Telnyx products send HTTP callbacks when asynchronous events occur. Event schemas, retry schedules, failover behavior, and configuration fields are product-specific. Use this page for the common handling contract, then follow the selected product’s webhook reference.

​
Delivery contract

  1. Preserve the raw request body and request headers.
  2. When the selected product documents Ed25519 signing, preserve telnyx-timestamp and telnyx-signature-ed25519, verify the signature before trusting the event, and reject signatures outside the application’s replay window.
  3. Record the event identifier and product correlation identifiers.
  4. Queue the accepted event and return the product’s required success status promptly.
  5. Process the event asynchronously and idempotently.
Do not depend on single delivery or delivery order. Events can be concurrent, duplicated, delayed, or delivered out of order. Reconcile state using occurred_at and product resource identifiers where available.

​
Configure the endpoint

Configure the primary webhook URL in the corresponding product application or profile. Configure a failover URL when the product supports one. Use an HTTPS endpoint with a valid certificate for production integrations. For local testing, expose a local handler with the ngrok setup guide. Do not send production payloads containing sensitive data to public request-inspection services.

​
Verify an Ed25519 signature

Products that document Telnyx Ed25519 signing use the account’s key pair. The public key is available in Mission Control Portal. Follow another signing or validation scheme when the selected product defines one. Verification requires the exact body bytes received by the server. Do not parse and reserialize JSON before verification. Current server-side SDKs provide maintained verification helpers: The helpers accept the raw payload and request headers, verify the signature against TELNYX_PUBLIC_KEY, and return a parsed event. Treat a verification exception as an invalid or malformed delivery.
Parsing helpers whose names include unsafe do not verify the signature. Use them only after independent verification or in isolated tests.

​
Understand the event envelope

Many V2 JSON callbacks use a data event envelope:
The envelope is not universal. TeXML callbacks can be form-encoded, and product families can define different fields. Use the machine-readable webhook event catalog for the exact media type, source specification, and payload schema.

​
Acknowledge promptly

For event-notification webhooks, follow the selected product’s acknowledgment contract after validation and durable queueing. Many products accept any 2xx. Some products require 200. Use 200 when the product documentation does not specify another successful status. Telnyx does not use the response body to process ordinary event notifications. TeXML instruction requests and other product-specific callback protocols can use the HTTP response body; follow the relevant product documentation. Avoid database transactions, external API calls, media downloads, and other long-running work before acknowledgment.

​
Handle retries and duplicates

A delivery can be repeated when an acknowledgment is lost even if the first attempt completed. Use the event id as a deduplication key when supplied. Make downstream state changes conditional so replaying the event has no additional effect. Product-specific policies determine retry timing, timeout, and failover destinations. Do not implement one assumed schedule for every Telnyx webhook.

​
Preserve observability

Record the event identifier and type, occurred_at, delivery attempt when present, product resource identifiers, verification result, and queue and processing outcome. Do not log signing keys, full sensitive payloads, or authentication credentials.

​
Product references