Set up numbers to trigger webhooks

Using Mediahawk, you can trigger a webhook to your platform or server when a call hits our system as soon as the call starts ringing. This guide will help you see what webhooks are currently set up and create a new webhook to trigger when a call arrives to your number.

Before you begin this guide, please ensure you have followed the Authenticate guide and have a valid token.

You can download a full working code example for this guide here:

CURL, PHP, Node.js, Python, C#

List out your existing webhooks

First of all, list out your existing webhooks.

apiKey="<API_KEY>"

curl -L -X GET "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=${apiKey}" \
    --header "Content-Type: application/json"

$apiKey = "<API_KEY>";

$client  = new Client();
$headers = [
    "Accept"        => "application/json"
];
$request = new Request("GET", "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" . $apiKey, $headers);
$res     = $client->sendAsync($request)->wait();
echo $res->getBody();

import requests
import json

apiKey = "<API_KEY>"
url = "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey

# requests client
httpRequest = requests.Session();

webhookListResponse = httpRequest.request("GET", url)
webhookListResponseJson = json.loads(webhookListResponse.text)
print(json.dumps(webhookListResponseJson, indent=2))

const axios = require("axios");

let apiKey = "<API_KEY>";

let config = {
  method: "get",
  url:
    "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey,
  headers: {
    Accept: "application/json",
  },
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

using RestSharp;
using Newtonsoft.Json;

string apiKey = "<API_KEY>";

var restClient = new RestClient("https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey);
restClient.Timeout = -1;
var requestWebhooks = new RestRequest(Method.GET);
IRestResponse webhookListResponse = restClient.Execute(requestWebhooks);
Console.WriteLine(webhookListResponse.Content);

The response will appear here

Create a new webhook

Create a new webhook that will send a request to your endpoint when any call is received. This is the most basic webhook you can create.

Below, you will find an example payload for a webhook request. This can be customised in the webhook:

{
  "CallID": "12345",
  "ServiceNumber": "01234567890",
  "CallersNumber": "01234567890",
  "TerminatingNumber": "01234567890",
  "CallStart": "2022-01-01 13:12:00",
  "CampaignDescription": "My Campaign",
  "LastSource": "google",
  "LastMedium": "ppc",
  "FirstSource": "direc",
  "FirstMedium": "direct",
  "FirstKeyword": "mediahawk",
  "Keyword": "mediahawk",
  "VisitorID": "12345",
  "GoogleClickID": "123467",
  "MediaChannel": "My Channel",
  "MediaOwner": "My Owner",
  "MediaDescription": "My Description",
  "Department": "My Department",
  "CallTags": "utm_content=abc",
  "CallRef": "23456",
  "PageURI": "http://www.example.com/full/urls",
  "PageTitle": "My page title",
  "LandingPageURI": "http://www.example.com/full/urls",
  "LandingPageTitle": "My page title",
  "PaidSearchType": "1",
  "PaidSearchMatchType": "Broad",
  "PaidSearchAdGroupID": "356356356",
  "PaidSearchAdGroupName": "adgroup name",
  "PaidSearchCampaignID": "5757857857",
  "PaidSearchCampaignName": "campaign name",
  "GoogleClientId": "986977467",
  "PoolDescription": "my pool",
  "CallMHID": "AFGvfg45HT",
  "VisitMHID": "rtGF576fTB",
  "VisitorMHID": "sfg53GF87f"
}

To create the webhook. The only thing you have to provide is the endpoint.

apiKey="<API_KEY>"
endpoint="<ENDPOINT>"
curl -L -X POST "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=${apiKey}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data '{ "endpoint": "'$endpoint'" }'

$apiKey = "<API_KEY>";
$endpoint = "<ENDPOINT>";
$client  = new Client();
$headers = [
    "Content-Type"  => "application/json",
    "Accept"        => "application/json"
];
$body = json_encode([
    "endpoint" => $endpoint,
]);

$request = new Request("PUT", "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" . $apiKey, $headers, $body);
$res     = $client->sendAsync($request)->wait();
echo $res->getBody();

import requests
import json

apiKey = "<API_KEY>"
endpoint = "<ENDPOINT>"
url = "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey

# requests client
httpRequest = requests.Session();

payload = json.dumps({
    "endpoint": endpoint
})
headers = {
    "Content-Type": "application/json"
}

response = httpRequest.request("POST", url, headers=headers, data=payload)
webhook = json.loads(response.text)
responseJson = json.loads(response.text)
print(json.dumps(responseJson, indent=2))

const axios = require("axios");

let apiKey = "<API_KEY>";
let endpoint = "<ENDPOINT>";

let data = JSON.stringify({
  endpoint: endpoint,
});

let config = {
  method: "post",
  url:
    "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey,
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: data,
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

using RestSharp;
using Newtonsoft.Json;

string apiKey = "<API_KEY>";
string endpoint = "<ENDPOINT>";

var restClient = new RestClient("https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks?api_key=" + apiKey);
restClient.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "application/json");

request.AddJsonBody(new { endpoint = endpoint });
IRestResponse response = restClient.Execute(request);
var responseObject = JsonConvert.DeserializeObject<dynamic>(response.Content);
Console.WriteLine(responseObject);

The response will appear here

Customise your webhook to only trigger for specific numbers

If you want your webhook to only trigger for specific numbers or Dynamic Pools, you can do this using the:

number_acl - This allows you to allow or deny this webhook for specific static numbers
url_acl - This allows you to allow or deny this webhook for specific Dynamic URLs
destination_acl - This allows you to allow of deny this webhook for specific destinations

info

The ACLs work by matching (**number_acl** OR **url_acl**) AND **destination_acl** to work out whether to trigger.

Using this request, you can modify the webhook we created earlier to only trigger when a specific number is called, and set it to not send if we are calling a specific destination. We also can set it to email us if there is a problem with the webhook.

apiKey="<API_KEY>"
webhookId="<WEBHOOK_ID>"

# Numbers in E.164 format with no leading plus (e.g. 44111222333)
staticNumber="<STATIC_NUMBER>"
destinationNumber="<DESTINATION_NUMBER>"
failureEmail="<FAILURE_EMAIL>"

curl -L -X PATCH "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks/${webhookId}?api_key=${apiKey}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data '{
        "failures_email": "'$failureEmail'",
        "number_acl": {
            "type": "allow",
            "service_numbers": [
                "'$staticNumber'"
            ]
        },
        "destination_acl": {
            "type": "block",
            "destinations": [
                "'$destinationNumber'"
            ]
        }
    }'

$apiKey            = "<API_KEY>";
$wenhookId         = "<WEBHOOK_ID>";
$failureEmail      = "<FAILURE_EMAIL>";

// Numbers in E.164 format with no leading plus (e.g. 44111222333)
$staticNumber      = "<STATIC_NUMBER>";
$destinationNumber = "<DESTINATION_NUMBER>";

$client  = new Client();
$headers = [
    "Content-Type" => "application/json",
    "Accept"       => "application/json",
];
$body = json_encode([
    "failures_email"  => $failureEmail,
    "number_acl"      => [
        "type"            => "allow",
        "service_numbers" => [
            $staticNumber,
        ],
    ],
    "destination_acl" => [
        "type"         => "block",
        "destinations" => [
            $destinationNumber,
        ],
    ],
]);

$request = new Request("PATCH", "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks/" . $webhookId . "?api_key=" . $apiKey, $headers, $body);
$res     = $client->sendAsync($request)->wait();
echo $res->getBody();

import requests
import json

apiKey = "<API_KEY>"
webhookId = "<WEBHOOK_ID>"
failureEmail = "<FAILURE_EMAIL>"

# Numbers in E.164 format with no leading plus (e.g. 44111222333)
staticNumber = "<STATIC_NUMBER>"
destinationNumber = "<DESTINATION_NUMBER>"

url = "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks/" + webhookId + "?api_key=" + apiKey

# requests client
httpRequest = requests.Session();

payload = json.dumps({
  "failures_email": failureEmail,
  "number_acl": {
    "type": "allow",
    "service_numbers": [
      staticNumber
    ]
  },
  "destination_acl": {
    "type": "allow",
    "destinations": [
      destinationNumber
    ]
  },
})

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = httpRequest.request("POST", url, headers=headers, data=payload)
webhook = json.loads(response.text)
responseJson = json.loads(response.text)
print(json.dumps(responseJson, indent=2))

const axios = require("axios");
let apiKey = "<API_KEY>";
let webhookId = "<WEBHOOK_ID>";
let failureEmail = "<FAILURE_EMAIL>";

// Numbers in E.164 format with no leading plus (e.g. 44111222333)
let staticNumber = "<STATIC_NUMBER>";
let destinationNumber = "<DESTINATION_NUMBER>";
let data = JSON.stringify({
  failures_email: failureEmail,
  number_acl: {
    type: "allow",
    service_numbers: [staticNumber],
  },
  destination_acl: {
    type: "block",
    destinations: [destinationNumber],
  },
});

let config = {
  method: "patch",
  url:
    "https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks/" +
    webhookId +
    "?api_key=" +
    apiKey,
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: data,
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

using RestSharp;
using Newtonsoft.Json;

string apiKey = "<API_KEY>";
string id = "<WEBHOOK_ID>";
string failuresEmail = "<FAILURE_EMAIL>";

// Numbers in E.164 format with no leading plus (e.g. 44111222333)
string staticNumber = "<SERVICE_NUMBER>";
string destinationNumber = "<DESTINATION_NUMBER>";

var restConfigureClient = new RestClient("https://www.reports.mediahawk.co.uk/rest/v2_0/webhooks/" + id + "?api_key=" + apiKey);
restConfigureClient.Timeout = -1;

var webhookConfigureRequest = new RestRequest(Method.PATCH);
webhookConfigureRequest.AddHeader("Content-Type", "application/json");
webhookConfigureRequest.AddHeader("Accept", "application/json");

// Configure new webhook with number and destination, as well as failure email
string[] service_numbers = { staticNumber };
string[] destinations = { destinationNumber };

webhookConfigureRequest.AddJsonBody(JsonConvert.SerializeObject(new
{
    failures_email = failuresEmail,
    number_acl = new
    {
        type = "allow",
        service_numbers
    },
    destination_acl = new
    {
        type = "block",
        destinations
    }
}));

IRestResponse webhookConfigureResponse = restConfigureClient.Execute(webhookConfigureRequest);
var webhookConfigureResponseObject = JsonConvert.DeserializeObject<dynamic>(webhookConfigureResponse.Content);
Console.WriteLine(webhookConfigureResponseObject);

The response will appear here

Set up numbers to trigger webhooks

List out your existing webhooks​

Create a new webhook​

Customise your webhook to only trigger for specific numbers​

List out your existing webhooks

Create a new webhook

Customise your webhook to only trigger for specific numbers