Webhook Integration

1. Introduction

The CDR Manager Webhook integration is a feature that allows the CDR task reports to be delivered by setting up a webhook. When a webhook is set up, as soon as a CDR task is done and a report is exported, a webhook sends a request to a webhook URL, with a payload containing a link for pulling the report.

The advantage of a webhook is that it sends data in real time, whenever the relevant event happens.

The feature will run immediately upon being notified by the CDR Manager app that the report is available. System sends an HTTP request with a payload to a webhook URL.

2. Webhook Configuration

This feature can be enabled while defining a new CDR task in the Platform CDR Manager section. After setting up all the filters' details for the CDR task, a Webhook option can be selected for a report delivery.

After the Webhook option is selected, additional fields will be shown for selecting the previously set webhook configuration or for adding a new one.

After selecting the option to add a new webhook configuration, a new window will be opened.

To configure a new webhook, the following data are needed:

Configuration Name - The Webhook configuration name.
Full URL - The Webhook URL to which a POST request will be sent with a payload.
Signature - Signature key is a random string for signing and validating requests.

Each request data (what we send to the given URL) is signed with the signature key from a configuration with sha512 algorithm which is base64 encoded. The signature key will be in the request header field [X-CDR-Signature]. The exact function for signing a request is:

return base64_encode(hash_hmac('sha512', $inputBodyJSON, $signature, true));

This way it is possible to check authenticity of the request.

The expected format of a payload that will be sent in the request is presented below:

{
  "contentType": "application/zip",
  "httpMethod": "GET",
  "callbackURL": "https://example.com/bulk/cdr-mgr/v1/cdr-download-files/012e93de-1fae-4c6d-8067-c27c4cb9fdtg",
  "validUntil": "2023-01-10T10:02:27Z",
  "fileName": "tx00001.zip",
  "fileSizeInBytes": 100000,
  "numberOfLines": 100,
  "taskName": "Example task",
  "taskId": 1,
  "error": "Error message"
}

The destination should understand our payloads. From the provided payload, the needed data for pulling the report can be found. The payload contains the callback URL with an access token, where the report is stored. The access token is valid for 24 hours, i.e. until the date and time as listed in a payload.

If any error occurs, the error message as a string will be sent within a payload. Otherwise, the error value will be an empty string.

The IP address of the Platform instance that sends a requests will be presented at the bottom of the window, so it can be whitelisted if needed.

3. Data Model

Data Model defines the structure of a JSON document. It describes the data related to a webhook's payload.

WebhookDescriptionBody object properties:

JSON example

{
  "contentType": "application/zip",
  "httpMethod": "GET",
  "callbackURL": "https://example.com/bulk/cdr-mgr/v1/cdr-download-files/012e93de-1fae-4c6d-8067-c27c4cb9fdtg",
  "validUntil": "2023-01-10T11:20:09Z",
  "fileName": "tx00001.zip",
  "fileSizeInBytes": 100000,
  "numberOfLines": 100,
  "taskName": "Task Name Example",
  "taskId": 1,
  "error": ""
}