Что такое Webhook

Webhook это способ извещения систем пользователя об обнаружении в ТВ-эфире видеоклипа.

Это извещение осуществляется с помощью отправки по протоколу http или https запроса на задаваемый пользователем URL.

AdSwitcher Webhook может использоваться для интеграции с другими сервисами, которые поддерживают эту технологию, например, с веб-сайтами или другими системами. Таким образом, выход в ТВ-эфир заданных видеоклипов может повлечь определённое пользователем поведение этих систем.

Настройка и конфигурирование

В каждой кампании AdSwitcher пользователь может настроить один Webhook.

Для настройки необходимо проделать следующие минимальные действия:

  • в настройках кампании AdSwitcher нажать кнопку Добавить Webhook;
  • в поле «URL вызываемого триггера» указать URL на который будет отправлен POST-запрос. Явно укажите используемый протокол: http или https.

При необходимости получения в webhook-извещении собственной произвольной информации, можно поместить строку с ней в поле "Дополнительные данные".

При обнаружении в ТВ-эфире клипа, пользователь получит на заданный URL POST-запрос, содержащий JSON-объект со следующими свойствами:

  • timestamp — временная метка в формате unix timestamp;
  • campaign_id — числовой идентификатор кампании AdSwitcher;
  • userdata — строка, заданная пользователем в поле «Дополнительные данные» при конфигурировании webhook в настройках кампании AdSwitcher. Если поле «Дополнительные данные» в свойствах кампании AdSwitcher не заполнено, JSON-объект не имеет этого свойства.

Безопасность

Когда сервер, URL которого задан в настройках webhook, обрабатывает запросы от разных отправителей, может потребоваться подтверждение того что запрос получен именно от AdSwitcher. Для такого подтверждения в настройках Webhook кампании AdSwitcher можно задать произвольную строку в поле «Secret».

Если это поле заполнено, POST-запрос будет иметь заголовок X-ADSWITCHER-SIGNATURE, содержащий MD5 HMAC дайджест тела POST-запроса. В качестве ключа используется строка заданная в в поле «Secret» в настройках Webhook.

Проверка

Для того чтобы проверять поведение своей системы при получении AdSwitcher Webhook, пользователь может использовать кнопку «Отправить тестовый запрос», находящуюся в настройках Webhook кампании AdSwitcher. При её нажатии на URL, указанный в настройках Webhook, будет отправлен POST-запрос с содержимым, идентичным содержимому отправляемому при обнаружении в ТВ-эфире клипа.

Если кнопка «Отправить тестовый запрос» нажата в режиме создания новой (ещё не сохранявшейся) кампании AdSwitcher, пользовательская система получит POST-запрос с webhook в котором поле campaign_id будет содержать 0.

Примеры

Пример тела запроса с заданным значением поля userdata:

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

Пример тела запроса с пустым полем userdata:

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

Пример проверки отправителя с использованием MD5 HMAC Digest на 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;
}