Skip to main content

Webhooks

Webhooks are outbound HTTP requests sent from the Voxtelesys platform to your application in response to real-time events. They enable event-driven workflows by allowing your server to programmatically react to actions such as inbound calls, SMS/MMS delivery receipts (DLRs), or recording availability.

Webhooks are user-defined HTTP callbacks that are triggered by certain events in a web application. They help integrate different applications or third-party APIs, like Voxtelesys.

How Webhooks Work​

When a webhook-enabled event occurs, Voxtelesys performs an HTTP request to the endpoint you’ve configured—typically using the POST method, though GET may be used in some cases. The request includes a payload with event-specific metadata and parameters, allowing your application to make decisions or trigger downstream processes.

Depending on the API, the request body is encoded as either application/json or application/x-www-form-urlencoded. Each webhook is versioned and documented with a complete schema, including parameter descriptions, data types, and example payloads.

To ensure reliability, Voxtelesys will retry delivery of webhooks on failure (e.g., non-2xx HTTP status codes) based on an exponential backoff strategy. You are expected to acknowledge webhook delivery with a timely 2xx response; other status codes may result in retries or fallback behavior.

Webhook Types​

Voxtelesys supports two primary webhook modes:

  • Informational Webhooks These webhooks provide information about events, such as when a voice call recording is ready for download. Informational webhooks are one-way event notifications. No response is required beyond a 2xx status code.

  • Actionable Webhooks These webhooks require your application to return a response payload that influences call flow or session behavior.

Security & Authentication​

Voxtelesys requires all webhook callback endpoints to be accessible over HTTPS with a valid, publicly trusted TLS certificate. Requests sent over insecure HTTP or with self-signed/untrusted certificates will be rejected.

To protect webhook endpoints from unauthorized access, Voxtelesys supports the following HTTP authorization mechanisms:

Token Authentication​

Voxtelesys will include a standard Authorization header using the provided Token:

Authorization: Bearer <your-token>

Basic Authentication​

Voxtelesys will include a standard Authorization header using the provided Username and Password:

Authorization: Basic <base64(username:password)>