General Information

Incoming webhooks are endpoints your application registers to get real-time updates so that your integration can automatically trigger reactions and new workflows.

VoiStrix uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when an inbound or outbound call is made or received, or when new phone events are provisioned.

How VoiStrix uses webhooks

A webhook enables VoiStrix to push real-time notifications to your application. VoiStrix securely uses HTTPS to send these notifications to your application as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Create an application with VoiStrix

Applications are created on the Account Settings page under the Applications menu. You must be an account owner to create or modify applications. You can create multiple applications or utilize a single application to process webhook events.

How to create a webhook endpoint

Creating a webhook endpoint is no different from creating any other page on your website. It's an HTTPS endpoint on your server with a URL. If you're still developing your endpoint on your local machine, it can be HTTP or you can use a tool such as ngrok to secure your local endpoint. After it's publicly accessible, it must be HTTPS. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Your endpoint will require you to secure your data by accepting an Authorization header where VoiStrix will populate with the value you chose during application creation.

Handle requests from VoiStrix

Your endpoint must be configured to read the specific webhook request object for the type of event notifications you want to receive. VoiStrix sends events to your webhook endpoint as part of a POST request with as JSON payload.

Check JSON Payload

Each event is structured to include an applicationID and webhookType with the addition of the event specific data in the payload. Your endpoint must check the webhook type and parse the payload of each event.

Validate and authorize the request

VoiStrix will POST to the provided webhook and fill in the value of the Authorization header with the information provided during application creation. It is recommended that you check the Authorization header against this specified value to validate the request and protect your endpoint from unauthorized requests.

Return a 2xx response

Your endpoint must quickly return a successful status code 2xx. Any other status code will trigger the retry logic.

Built-in retries

VoiStrix webhooks have built-in retry logic for any methods that return non 2xx status codes. If VoiStrix does not quickly receive a 2xx response status code for an event, we mark the event as failed and begin retrying several times for the next few minutes. After multiple failures we will first email you about the misconfigured endpoint, and automatically disable your application soon after if you have not addressed the issue.