Webhooks

Prev Next

Who should read this article: Administrators

Voiso's Webhooks feature allows you to subscribe to call events and integrate them into your automated workflows, custom applications, and external systems.

Note

The Webhooks feature is available for contact centers on the Pro plan or higher.

Introduction

Webhooks enable real-time communication between applications by sending HTTP requests containing event data when a predefined trigger occurs. This allows you to automate processes, synchronize data, and build integrations tailored to your business needs.

For a complete list of Voiso webhook events and their payload structures, refer to the Webhooks overview in the Voiso developer documentation.

Security Notice

To protect your data, only secure HTTPS endpoint URLs are supported for webhooks.

Managing Webhooks

To create and manage webhooks:

  1. In the Voiso navigation bar, go to Administration > Webhooks.
  2. The Webhooks page displays a list of existing webhooks configured for your contact center.
  3. Click a webhook name to view or edit its settings.
  4. Click Add webhook to create a new webhook.
  5. To delete a webhook, hover over its row and click the Delete (trash can) icon.

Webhooks Webhoooks Main Page

Creating a Webhook

To set up a new webhook, click Add webhook to open the Add webhook page. Complete the information required for each of the sections, then click Save to finalize the webhook configuration:

Webhooks Add Webhoook Page

General section

The General section defines the core configuration for your webhook. These settings determine how the webhook is identified, where event notifications are delivered, and how request authenticity can be verified. Complete the following fields to establish a secure connection between your contact center and your external system.

  • Webhook name – Enter a descriptive name that aligns with your business process.
  • Endpoint URL – Specify the HTTPS URL where webhook notifications should be sent.
  • Secret key (optional) – Enter a secret key for validating webhook requests on your system.

Authentication section

Use authentication to safeguard your data and contact center by ensuring that your webhook traffic is not exposed to spoofing, data tampering, or unauthorized access. There are four authentication options available from the Method menu:

  • None – Not recommended. Disabling authentication means webhook traffic is sent without any verification, leaving your system vulnerable to spoofing, tampering, and unauthorized access. Consider using a custom header to provide an authentication key-value pair.
  • API key – This method uses a custom header to transmit a static key. You define both the header name and the key value. The receiving system checks incoming requests for the expected header and key pair. This approach is straightforward to implement and effective for simple validation use cases.
  • Basic – This method uses HTTP Basic Authentication by encoding a username and password combination into a base64 string. The credentials are included in the Authorization header of each webhook request. This method is widely supported and useful when integrating with systems that require username/password-based authentication.
  • Bearer token – This method includes a token in the Authorization header using the Bearer scheme (e.g., Authorization: Bearer your-token). The receiving system verifies the token to confirm the request is legitimate. Bearer tokens are commonly used with OAuth 2.0 or similar token-based authentication mechanisms and are suitable for more secure, token-driven environments.

Headers section

The custom headers feature allows you to define up to five additional header key-value pairs to include in each webhook request. These headers can be used to pass extra information—such as authentication tokens, environment identifiers, or integration-specific metadata—alongside the payload. This is useful when the receiving system expects specific headers for request validation, routing, or logging.

Click Add header to display the Key and Value fields. Enter a key name and value, such as x.client.signature and 3ab24f91d6e84917a6f75bd849afc2ef.

Click X to remove a header key-value pair.

Events section

In the Events section, select one or more supported interaction events that should trigger the webhook. For a full list of available options, refer to the Supported Events table in the developer documentation. If an event is already assigned to another webhook, it will be unavailable for selection.

Transfer information on call events

When a call is transferred, the call events list every transfer made on the call, in the order they happened. Your system can use this to credit the agent who finished the call and to see where the call went.

These events include the transfers:

  • inbound.call.hangup and inbound.call.ended
  • outbound.call.hangup and outbound.call.ended
  • dialer.call.hangup and dialer.call.ended
  • call.recording.available

For each transfer, the event shows:

  • Where the call went – an agent, a queue, or an external number.
  • How it was transferred – a blind transfer or a consult transfer.
  • Who or what received it – the agent's or queue's name, ID and extension, or the external number.
  • When – the time of the transfer.

A handoff from an AI agent to a human agent is listed as a blind transfer to that agent. A handoff to a SIP URI is listed as a transfer to an external number, with the SIP URI as the number.

When an Inbound call workflow routes a call to a queue or an agent, this is not a transfer, so it is not listed. Calls without a transfer send the same events as before.

Tip

*.call.ended is sent when each agent finishes wrap-up, so the event of an agent who transferred the call does not list transfers made after they left it. For the full list of transfers on a call, use *.call.hangup or call.recording.available.

For the fields and an example, refer to the Transfer object in the Voiso developer documentation.

Monitoring and retrying inactive webhooks

Webhook events are maked as Inactive after five failed delivery attempts. Inactive events are flagged with a notification icon in the webhook list.

To programmatically manage failed deliveries:

Note

These endpoints are intended for users with custom webhook implementations who need to detect and resolve failures outside of the Voiso application.