Webhook + Slack¶

Webhook¶

Webhook позволяет получать HTTP-оповещения в реальном времени. При срабатывании триггера, Boro cервер отправляет HTTP POST запрос в формате JSON на указанный IP-адрес пользователя.

Создание и применение профиля¶

Для добавления профиля Webhook-оповещений откройте страницу настроек проекта, перейдите к вкладке Уведомления➝Webhook и выберите действие Создать профиль.

Убедитесь, что настройка Включить оповещения Webhook (1) активна.

Настройка Webhook¶

В поле URL (2) введите URL или IP-адрес сервера, на который следует отправлять Webhook-оповещения. Дополнительно на странице профиля можно также задействовать следующие настройки оповещений:

Подписывать запросы (3) — настройка позволяет добавлять в HTTP заголовок поле Authorization: APIAuth-HMAC-SHA256 <profile id>:<signature>, где:
- <profile id> — ID профиля Webhook-оповещения на сервере Boro;
- <signature> — вычисляется как результат HMAC-SHA-256(«<HTTP Method>,<Content-Type>,<Content-Sha256>,<Request-URI>,<Date>»,»mysecretkey»).
Секретный ключ (4) — секретный ключ в шестнадцатеричном формате, используемый для создания подписи запросов. Сгенерируйте ключ и сохраните его в надежном месте, он понадобится если вы организуете проверку подписи на приемной стороне;
Пользовательские заголовки в HTTP запросе (5) — настройка позволяет добавить несколько пользовательских заголовков и их значений в HTTP запрос. Кроме этого, можно заменить значения стандартных заголовков Content-Type и User-Agent на пользовательские значения.
- Заголовок (6) — название поля заголовка в HTTP запросе.
- Значение (7) — значение поля заголовка в HTTP запросе.

Для проверки корректности установленных настроек нажмите кнопку Отправить тестовое сообщение (8). Если тестовое сообщение было доставлено, сохраните профиль.

Формат оповещений¶

Каждое срабатывание триггера вызывает отправку нового оповещения (сообщения не объединяются в один запрос). Сообщения отправляются как HTTP POST запрос в формате JSON и содержат следующие поля:

version — версия протокола;
sequenceId — идентификационный номер сообщения;
referenceNumber — (опциональное поле) референсный номер сообщения. Предназначен для связывания сообщений о возникновении состояния ошибки и ее завершении;
project_name — имя проекта, из которого пришло оповещение;
probe_name — имя зонда, который зарегистрировал событие;
task_uri — URI потока или сервиса, для которого зарегистрировано событие;
task_name — имя задачи, для которой зарегистрировано событие;
subtask_uri — (опциональное поле) применяется для HLS, SRT, DASH. В зависимости от типа потока передает URI медиапредставления (варианта потока для HLSv3 или URI SRT потока), для которого зарегистрировано событие;
subtask_description — (опциональное поле) применяется для протоколов HLS, SRT, DASH. Передает описание медиапредставления (варианта потока для HLSv3) или описание SRT потока;
trigger — название сработавшего триггера (на выбранном языке);
status — статус состояния ошибки Active|Cleared или Event, если триггер относится к типу «Событие»;
level — уровень важности события (задается в настройках профиля оповещения);
time — время срабатывания триггера типа «Событие» или время возникновения состояния;
time_end — (опциональное поле) время завершения состояния;
duration — (опциональное поле) длительность состояния;
profile_name — имя профиля оповещения, в котором было зарегистрировано событие;
links — (опциональное поле) массив ссылок в системе Boro:
- type — определяет тип объекта, для которого представлена ссылка. Возможны следующие значения:
  
  task — ссылка на родительскую задачу (Манифест для OTT, Мастер для SRT) в системе Boro;
  
  subtask — ссылка на дочернюю задачу анализа медиапредставления (OTT) или потока (SRT) в системе Boro;
  
  profile — ссылка на страницу с профилем Webhook, который назначен задаче анализа.
- href — ссылки.
pid — (опциональное поле) информация о PI-идентификаторе, для которого сработал триггер;
count_by_pids — (опциональное поле) массив, распределение ошибок по каждому из PID-идентификаторов, только для CC ошибок;
count — (опциональное поле) количество ошибок, только для триггеров типа «Событие»;
details — (опциональное поле) объект, содержит дополнительную информацию об ошибке:
- curl_error — (опциональное поле) объект, содержит описание и коды ошибок, возвращаемые модулем libcurl, во время организации соединения с HTTP сервером;
- http_error — (опциональное поле) объект, содержит код HTTP ошибок, возникающих при загрузке объектов (плейлистов, ключей, сегментов) для HLS и DASH протоколов;
- source_ip — (опциональное поле) конечный IP-адрес при загрузке объектов (плейлистов, ключей, сегментов) для HLS и DASH протоколов.

Пример оповещения о Разрывах меток синхронизации¶

 {
   "version":"1.1",
   "sequenceId":666,
   "referenceNumber":7189705,
   "project_name":"Elecard Network",
   "probe_name":"Development probe",
   "task_uri":"http://10.10.30.53:8080/DASH/DASH.mpd",
   "task_name":"DASH AllRenditions",
   "subtask_uri":"http://10.10.30.53:8080/Match/HQ_video",
   "subtask_description":"video(HQ_video 4 Mb/s: 1280x720, avc1.4D001F)",
   "trigger":"Разрыв меток синхронизации",
   "status":"Cleared",
   "level":"major",
   "time":"2022-04-13T16:16:38.849+07:00",
   "time_end":"2022-04-13T16:16:39.743+07:00",
   "duration":"1 s",
   "count":3,
   "count_by_pids":{
     "1001":3
   },
   "profile_name":"new profile",
   "links":[
     {
       "type":"task",
       "href":"http://172.16.11.111/projects/23/apps/1105/tasks/330566"
     },
     {
       "type":"subtask",
       "href":"http://172.16.11.111/projects/23/apps/1105/tasks/330569"
     },
     {
       "type":"profile",
       "href":"http://172.16.11.111/projects/23/profiles?notif_id=265"
     }
   ]
 }

Настройка оповещений о событиях проекта в Slack¶

Используя Webhook-профиль можно настроить отправку уведомлений в Slack. Отправка уведомлений в Slack реализуется через Incoming Webhooks. Необходимо зарегистрировать Incoming Webhooks в аккаунте Slack.

Настройка Slack конфигурации¶

Откройте приложение Slack и в выпадающем меню выберите пункт Administration➝Manage Apps, в браузере будет открыта страница Apps.

В меню Manage выберите Custom Integrations. В списке настраиваемых интеграций (Configured Custom Integrations) кликните на Incoming WebHooks. В случае если ранее данная конфигурация не была задействована, необходимо ее предварительно добавить — введите её название в область поиска и перейдите на страницу работы с конфигурацией.

Необходимо добавить конфигурацию, кликнув на кнопку Add to Slack.

В выпадающем списке Post to channel выберите канал, куда следует отправлять оповещения, и нажмите кнопку Add Incoming WebHooks Integration.

../../../_images/IncomingIntegration.png

После выбора канала будет открыта страница Setup Instructions. В поле Webhook URL отображается путь, который используется для отправки уведомлений в Slack. Скопируйте данную строку, перейдите к веб-интерфейсу Boro и вставьте скопированную строку в поле URL, после чего сохраните изменения.

Чтобы изменить созданную ранее Slack конфигурацию, перейдите на страницу Incoming Webhooks. Во вкладке Configuration отображается список всех настроенных конфигураций, выберите нужную конфигурацию и кликните на значок EditIconSlack . На странице конфигурации возможно внесение следующих изменений:

Изменение канала получателя Webhook оповещений;
Генерация нового пути Webhook URL;
Выключение или удаление конфигурации (действия Disable, Remove).

Отправка оповещений¶

Оповещения о событии в проекте отправляются в формате JSON, в формате ключ-значение. Список полей подробно описан в пункте Формат оповещений. Ниже приведен пример оповещения, отправляемого при возникновении события в проекте, после того как были выполнены все необходимые настройки.

../../../_images/slackNotification_ru.png