What is Webhook

Webhook is a way to notify the user's systems about the detection of a video clip on TV.

This notification is performed by sending a request via http or https for a user-defined URL.

AdSwitcher Webhook can be used to integrate with other services that support this technology, for example, with websites or other systems. Thus, the perfoming on TV the specified video clips may entail user defined behavior of these systems.

Settings and configuration

In each AdSwitcher campaign, the user can configure one Webhook.

To configure you need to do the following minimum steps:

  • in the AdSwitcher campaign settings, click Add Webhook;
  • in the field «trigger URL » specify the URL to which the POST request will be sent. Explicitly specify the protocol to use: http or https.

If you need to get your own arbitrary information in a webhook-notification, you can put a line with it in the "Additional data" field.

When a clip is detected on TV, the user will receive a POST request containing a JSON object with the following properties:

  • timestamp — time in unix timestamp format;
  • campaign_id — numeric AdSwitcher-campaign id;
  • userdata — string, defined in field «Additional data» when configuring webhook in AdSwitcher campaign settings. If the field «Additional data» In the properties of the AdSwitcher campaign is not filled, the JSON object does not have this property.

Security

When a server whose URL is set in the webhook settings, processes requests from different senders, it can You need to confirm that the request was received from AdSwitcher. For such confirmation in You can set an arbitrary string in the field Webhook AdSwitcher settings «Secret».

If this field is filled in, the POST-request will have a header X-ADSWITCHER-SIGNATURE, containing MD5 HMAC digest of the POST requests body . The key used is the string specified in the field «Secret» of the Webhook settings.

Testing

In order to check the behavior of your system when receiving the AdSwitcher Webhook, the user can use the button «Send test request» in Webhook section of AdSwitcher-campaign settings. When you click this button, a POST request will be sent to the URL specified in the Webhook settings. This POST is the same as when detecting a clip.

If button «Send test request» clicked when you creating new AdSwitcher campaign and this campaign isn't saved, the user system will receive webhook with 0 in field campaign_id.

Examples

An example of a request body with a specified field userdata:

{
    "timestamp": 123, 
    "campaign_id": 6788, 
    "userdata": "some string"
}

Sample request body with empty field userdata:

{
    "timestamp": 123, 
    "campaign_id": 6788, 
}

Example of sender verification using MD5 HMAC Digest on PHP:

$yourSecret = '123456';

$allHeaders = getallheaders();
if (!isset($HTTP_RAW_POST_DATA) ||
    !isset($allHeaders['X-ADSWITCHER-SIGNATURE']) ||
    $allHeaders['X-ADSWITCHER-SIGNATURE'] !== hash_hmac('md5', $HTTP_RAW_POST_DATA, $yourSecret)) {
    exit;
}