Introduction
At the end of this article, you will be able to integrate Webhooks triggers of calls from our PBX system into your preferred system. Should you need any assistance, feel free to contact our support department.
Configuring Webhooks
Global webhooks can be configured to trigger various event types across the entire PBX. To configure the Webhook integration, firstly click on the "Integration/API" tab and select the Webhooks option from the left-hand menu. Then, enter the URL of the server to receive the webhook events in the URL field, and a string in the Secret Token field. This will be sent with each request via the HTTP header X-Pbx-Token for your server to validate. Next, select the tick box next to each event you would like to trigger a webhook event for, see below for further information on the details of each event. Please note, every time you make a change in the webhook section, you must apply configuration in your call flow.
If you are unsure of how to apply configuration in your call flow, click on the PBX tab and press the red button "apply configuration" as shown in the following image.
Webhook triggers
A short description of each triggered event currently supported can be found below:
- User inbound call: Webhook event is triggered when a call reaches a User Object and starts ringing. If the User is chosen via a Queue or Ring Group, the details of the object that the user is configured on will also be passed in the event.
- User inbound call answered: Webhook event is triggered when a call is answered by a User.
- User inbound call completion: Webhook event is triggered when a call to a User is completed.
- Queue call summary: Webhook event is triggered when call delivered via a queue object has ended.
- Ring group call summary: Webhook event is triggered when call delivered via a ring group object has ended.
- Voicemail: Webhook event is triggered when Voicemail is left.
- Inbound call recording: Webhook event is triggered when an inbound call has completed recording.
- User outbound call: Webhook event is triggered when a User initiates an outbound call.
- User outbound call answered: Webhook event is triggered when an outbound call from a user is answered by the called party.
- User outbound call completion: Webhook event is triggered when an outbound call from a user has ended.
- Outbound call recording: Webhook event is triggered when an outbound call has completed recording.
On the Webhooks configuration screen, select the webhooks triggers you wish to receive the data in JSON format. Additionally, by clicking on the dropdown list and selecting one of the triggers, a webhook response will be presented including the data type and its response to the triggered event. The text below the code shows a brief description of the variables presented in the JSON code.
As an example, the request below has been triggered by a "user inbound call" request. In this request, it is possible to identify the origin of the request, host, x-PBX-token, and call details. Within the call details, the caller ID, type of call, user name, user's extension, destination number, date, and queue information is presented. This data can be used and manipulated according to your business's needs to enhance your telephony system.
Webhook component event
Lastly, you may wish to customise a Webhook by using a Webhook object in the call flow. To set this up, select the PBX tab, click on "advanced options" from the left menu, and drag and drop the Webhook object onto the main screen. See attached image below of a customised webhook event that has triggered a call time-out of the queue. Headers can be configured on the object as required. The object can be placed anywhere in the call flow to meet your specific requirements.
The following HTTP Headers are sent with the webhook event, along with any additional headers defined on the webhook object;
x-pbx-token - The value defined in the Secret Token field on the webhook object
The following JSON data is sent with the webhook event;
(string) type - webhook_component_event
(string) unique_call_id - unique identifier of the call
(string) user_name - CNAM of the caller
(string) user_number - CallerID of caller (CLI)
(string) dest_number - phone number call was received on
(string) call_start_at - date and time when the call arrived on the PBX, in the ISO 8601 format
(string) component_name - name configured on the Webhook object
