This guide explains how to configure Webhook integration with third-party web applications and services, for sending events related to calls.

Created: August 2023

Permalink: https://wildix.atlassian.net/wiki/x/AYCODg

Introduction

Webhook integration (currently, in Beta) allows to connect different third-party web applications and services by sending events related to calls.  

Requirements 

How to configure the integration

1. Go to WMS -> PBX -> Integrations -> Calendarstab (or tox-beestab in case of a PBX with x-bees licence)

2. Click on the Webhook integration -> click Install 

3. On the Connect integration screen, fill out the following fields:

Select transmission type for sending the events:

a) In case of WebHook transmission type:

  1. In the Target field, indicate the URL where the data should be sent to. 
  2. Secret is generated automatically and cannot be edited. 
  3. Choose type of events: 
    1. Call start
    2. Call update
    3. Call end


b) In case of SQS transmission type:

  1. In the Target field, indicate the SQS URL where the data should be sent to.
  2. Enter SQS Key and Secret in the relevant fields. 
  3. Choose type of events: 
    1. Call start
    2. Call update
    3. Call end

4. Click Install.

Once installed, you can see details about the new integration which includes Integration ID, Transmission type, URL, Secret, and types of events selected. 

Note: Editing of the integration is currently not supported. If you need to update any data, please delete the current Webhook integration and create a new one. 


Copy the Integration ID and use it in your web application / service.

Important: The timeout for Webhook reply is 5 seconds. 


Important: For security reasons, it is highly recommended that you validate the data received to your web application / service and make sure the data comes from Wildix and the data is not broken. 

For this, check `signature` for all received events:

  • For webhook transport, you can find signature in the request's header x-signature
  • For SQS transport, you can find signature in the MessageAttributes ['X-SIGNATURE']

Configuration example

See Webhook configuration example on this page: https://github.com/Wildix/wildix-webhook-example.


Supported event types

Call start 

{
  "id": "it_w118741_1693389850.110",
  "pbx": "221100001bab",
  "time": 1693389850810,
  "company": "it_w118741",
  "type": "call:start",
  "integrationId": "8qkmnq",
  "data": {
    "status": "CONNECTING",
    "caller": {
      "type": "LOCAL",
      "phone": "1001",
      "name": "admin",
      "company": null,
      "email": "vladimir.gorobets@wildix.com",
      "userId": "1257510555",
      "userExtension": "1001",
      "userDepartment": null,
      "groupId": "62177694",
      "groupName": "Admin",
      "userAgent": "Wildix Zero Distance 4.0.1 WebRTC-f2a0f5f1-6c4e-444f-b99f-a968bb5f7297",
      "userDevice": "COLLABORATION_WEB"
    },
    "callee": null,
    "service": null,
    "destination": "10020",
    "trunkName": null,
    "queueName": null,
    "queueId": null,
    "tags": [],
    "flags": [],
    "endCause": null,
    "endCauseStr": null,
    "endBy": null
  }
}
```

Call update


{
  "id": "it_w118741_1693389850.110",
  "pbx": "221100001bab",
  "time": 1693389850810,
  "company": "it_w118741",
  "type": "call:update",
  "integrationId": "8qkmnq",
  "data": {
    "status": "CONNECTING",
    "caller": {
      "type": "LOCAL",
      "phone": "1001",
      "name": "admin",
      "company": null,
      "email": "vladimir.gorobets@wildix.com",
      "userId": "1257510555",
      "userExtension": "1001",
      "userDepartment": null,
      "groupId": "62177694",
      "groupName": "Admin",
      "userAgent": "Wildix Zero Distance 4.0.1 WebRTC-f2a0f5f1-6c4e-444f-b99f-a968bb5f7297",
      "userDevice": "COLLABORATION_WEB"
    },
    "callee": {
      "type": "LOCAL",
      "phone": "10020",
      "name": "user20",
      "company": null,
      "email": "vladimir.gorobets+3@wildix.com",
      "userId": "5753746",
      "userExtension": "10020",
      "userDepartment": null,
      "groupId": "874629312",
      "groupName": "Default",
      "userAgent": null,
      "userDevice": null
    },
    "service": null,
    "destination": "10020",
    "trunkName": null,
    "queueName": null,
    "queueId": null,
    "tags": [],
    "flags": [],
    "endCause": null,
    "endCauseStr": null,
    "endBy": null
  }
}
```

Call end

{
  "id": "it_w118741_1693389850.110",
  "pbx": "221100001bab",
  "time": 1693389853611,
  "company": "it_w118741",
  "type": "call:end",
  "integrationId": "8qkmnq",
  "data": {
    "status": "CONNECTING",
    "caller": {
      "type": "LOCAL",
      "phone": "1001",
      "name": "admin",
      "company": null,
      "email": "vladimir.gorobets@wildix.com",
      "userId": "1257510555",
      "userExtension": "1001",
      "userDepartment": null,
      "groupId": "62177694",
      "groupName": "Admin",
      "userAgent": "Wildix Zero Distance 4.0.1 WebRTC-f2a0f5f1-6c4e-444f-b99f-a968bb5f7297",
      "userDevice": "COLLABORATION_WEB"
    },
    "callee": {
      "type": "LOCAL",
      "phone": "10020",
      "name": "user20",
      "company": null,
      "email": "vladimir.gorobets+3@wildix.com",
      "userId": "5753746",
      "userExtension": "10020",
      "userDepartment": null,
      "groupId": "874629312",
      "groupName": "Default",
      "userAgent": null,
      "userDevice": null
    },
    "service": null,
    "destination": "10020",
    "trunkName": null,
    "queueName": null,
    "queueId": null,
    "tags": [],
    "flags": [],
    "endCause": "21",
    "endCauseStr": "Call Rejected",
    "endBy": "CALLER"
  }
}
```