With the Webhooks Module, you create a connection between your telephony and the internet. This module is mainly used for three purposes: CRM integration, switching based on an external database, and measuring online marketing campaigns (Google Analytics).


Creating a webhook

  • Click on add and agree to the costs.
  • Give a name and description to the webhook, for example 'CRM integration.'
  • Select which number the recipient of the call will see as caller ID, this can be done under passing on caller ID. Choose from 'Caller's number', 'Called number', and 'Suppressed (privacy).'
  • Fill in the URL template with the URL that should be called upon an incoming call.
  • For further explanation on setting up your Webhooks, refer to the Technical wiki:


Name: the name of the webhook used for selection in the call plan.

Description: purely administrative for an overview; not important for the functioning of the webhook.

Passing on caller ID: this allows you to select which number the recipient of the call sees as caller ID. You have the choice of "Caller's number", "Called number", and "Suppressed (privacy)".

URL-template: the most complicated field of the form. The help text in the form already provides some explanation. This field specifies how the URL to be called by the webhook should look. There are 4 variables that can be entered in the URL template:

  • {code}: the numerical code entered by the caller (see "Use IVR" below)
  • {did}: the called number
  • {callerid}: the caller's caller-ID
  • {callername}: the name of the caller, if available.

Use menu option: check this if you want a caller to enter a numeric code to proceed. After checking this, 5 extra fields will be visible:

Timeout: Enter the number of seconds the caller has to enter their digit code

Number of attempts: enter the number of attempts the caller has to enter the numeric code correctly

Initial message: Select here Audio Message which is played when the caller is routed to this Webhook.

Error message: select here Audio Message which is played when the caller has entered an incorrect numeric code.

A simple example of such a URL template is for instance:



Timeout report: select here Audio Message which is played when the number of seconds entered in Timeout is exceeded.


Setting up webhooks in the call plan

  • Press the plus sign, an additional step will appear on the screen.
  • Select the webhook for the recently added step and then choose the correct webhook.
  • Several sub-steps are being created:
    • HTTP and menu selection successful: the sub-steps within it are executed if the webhook has returned the correct values and the caller has entered a correct code if necessary.
    • HTTP of choice menu failed: in other cases, the sub-steps within it will be executed..

Variable Caller Name

The caller name - the name of the caller that the called party sees on their screen - can be manipulated in 3 ways:

Webhook: Set the caller name to the value returned by the webhook:

  • Add before: enter a text in the routing step text field that will be placed before the caller's name
  • Replace: enter text in the routing step's text field, this will now become the caller name.

Variable destination

If the webhook has returned a destination, it can be forwarded to it by selecting "Variable destination" in the routing step (under the webhook header):

The Feedback you can give to the system


The feedback you can give to the system is:


  • ACK -> Input is good
  • NAK -> Input is not correct
  • ERR -> Something went wrong


Used for forwarding to another destination: An example:


Use the following syntax to display the name of a caller or the status of a call (choices from an IVR) on a VoIP phone:

Example: an HTTP request has been successfully intercepted. The feedback is:


Commonly used application

The webhook module is mainly used for several purposes. CRM integration, switching based on an external database, measuring online marketing (Google Adwords) campaigns, and receiving an email when a call is missed.

CRM integration

When a call comes in, we send a pulse to the CRM package. This pulse contains the caller's number if known, and the dialed number. The customer returns the name to be displayed to our system, and we show this name on the screen of the VoIP phone..

Optionally, you can also have the CRM display a "customer card" based on the incoming call, but that requires intelligence to be present in the CRM package.

An example of this can be found on Examples of Webhook page.

Switching based on external database

We can forward incoming calls to a phone number returned by an external system. This can be done based on:

  • The caller's number
  • The dialed number
  • An entered PIN code

Tracking phone calls in Google Analytics

When tracking phone calls, you need a block of phone numbers. You assign a separate number to each campaign. With a block of 10 numbers, you can track 10 campaigns simultaneously.

Whenever a customer calls a number from the block, we invoke a URL containing the dialed number (the campaign) and the caller's number (if available). Our pulse does not process any JavaScript or similar, so after the URL is opened, a piece of code itself must be invoked to ensure the actual measurement of the conversion.

After the URL has been called, we forward the call to the company's number and measure the campaign.

Received email for a missed call

When a call is missed, it can be useful to receive the caller's phone number via email, SMS message, or through a platform like Slack, which includes the date, time, and called number. See Webhook examples for a detailed example using a Zapier connection with webhooks.

VIP pincode

It is possible to use the webhook to give customers a specific VIP code for, for example, a fault line. You can read how this works on the VIP pincode page.

Received an email for a missed call

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