Would you like to integrate your phone system with third-party software? (An action will be triggered by an inbound call.)

What is a Webhook?

User-defined HTTP call-backs, triggered by an inbound call. Commonly used for analytics or to integrate Freedom with your CRM. A Webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information.

A Webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes Webhooks much more efficient for both provider and consumer.

What can it do?

The Voys Webhooks feature allows you to connect your phone system to the Internet. This functionality is mainly used for 4 purposes:

  • Integration with your CRM.
  • Routing of inbound calls based on an external database.
  • Measuring conversions of marketing campaigns (Google Analytics).
  • Receive an email or other notification when you miss a call.
  • Use VIP PIN codes for routing
  • Dialling internal extensions directly from an IVR

How to configure a Webhook

  • Go to Admin >> Integration >> Webhooks
  • Click Add.
  • Enter Name e.g. CRM connection >> Caller id forwarding, number visible to call recipient >> URL-template, the URL that must be requested when triggered by an inbound call.
  • Un/Select Use IVR, check this box if you want a caller to enter a numerical code to proceed. After this box is checked, 5 extra fields become visible: Timeout: The number of seconds the caller has to make a selection. Maximum attempts: The number of times a caller can make an invalid selection. Start message: select the audio message that is played when the caller is routed to the Webhook. Incorrect message: select the audio message that is played when the caller makes an invalid selection. Timeout message: select the audio message that is played when the Timeout time is exceeded.
  • Click Save.
  • Click Dialplan (on the main navigation bar) >> Click on the on the desired number.
  • Click add step, it must always the final step in the Dialplan >>Select Web hook >> Select desired Web hook >>A few sub-steps are generated: HTTP and IVR success: the sub-steps here are followed when the Webhook has returned the correct values and, if applicable, the caller has made a correct selection (IVR). HTTP or IVR failed: in other cases, the sub-steps here are followed.Under these sub-steps, all steps can be added that can also be added in a normal Dialplan, plus a few extra options that are discussed below
  • Click Save on step >> Click Save for Dialplan.

Variable caller name

The caller name that is visible to the receiver of the call can be manipulated in 3 ways:

  1. Webhooks : configure the caller name to show the value that is returned by the Webhook
  2. Prefix : in the text field enter the text that you want to show in front of the caller name
  3. Replace : in the text field enter the text that will replace the caller name

Side note: Variable callername can also be used without Webhooks. In that case, only the options Prefix and Replace are available.

Variable destination

When the Webhook returns a destination, a call can be routed to this destination by selecting ‘Variable destination’ from the drop-down menu.

System Feedback

Feedback that can be sent to the system:

ACK : Selection (input) is valid

NAK : Selection is invalid

ERR : Something went wrong

For example, a HTTP request is successful:



Used for routing a call to another destination.

E.g. status=ACK&destination=%2B31502102544

Caller name

Used if you want to display the name of the caller, status of a call (IVR input), on a VoIP phone.

E.g. status=ACK&callername=VoysTelecom

I have feedback on your help pages!


We are constantly working on our platform and other products. If you want to stay informed of all updates, check for new updates

Still, want to speak to a colleague?

Can't quite figure it out or get it right? Call our Customer Happiness Team at 021 012 5000 or send an email to info@voys.co.za