4 Вебхук

Обзор

Тип медиа вебхук полезен для выполнения HTTP-вызовов с использованием пользовательского кода JavaScript для простой интеграции с внешним программным обеспечением, таким как системы helpdesk, чаты или мессенджеры. Вы можете импортировать интеграцию, предоставленную Zabbix, или создать собственную интеграцию с нуля.

Интеграции

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

Помимо перечисленных здесь сервисов, Zabbix можно интегрировать с Spiceworks (вебхук не требуется). Чтобы преобразовывать уведомления Zabbix в заявки Spiceworks, создайте тип медиа для электронной почты и укажите адрес электронной почты службы поддержки Spiceworks (например, help\@zabbix.on.spiceworks.com) в настройках профиля назначенного пользователя Zabbix.

Настройка

Чтобы начать использовать интеграцию с вебхуком:

  1. Найдите требуемый файл .yaml в каталоге templates/media загруженной версии Zabbix или скачайте его из git-репозитория Zabbix.
  2. Импортируйте файл в вашу установку Zabbix. Вебхук появится в списке способов оповещения.
  3. Настройте вебхук в соответствии с инструкциями в файле Readme.md (для быстрого доступа к Readme.md можно нажать на имя вебхука выше).

Чтобы создать пользовательский вебхук с нуля:

  1. Перейдите в Оповещения > Способы оповещения.
  2. Нажмите Создать способ оповещения.

Вкладка Способ оповещения содержит различные атрибуты, специфичные для этого способа оповещения:

Все обязательные поля ввода отмечены красной звёздочкой.

Следующие параметры являются специфичными для способа оповещения вебхук:

Параметр Описание
Параметры Укажите переменные вебхука как пары атрибут-значение.
Для предварительно настроенных вебхуков список параметров различается в зависимости от сервиса. Описание параметров смотрите в файле Readme.md соответствующего вебхука.
Для новых вебхуков по умолчанию включены несколько общих переменных (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); при необходимости их можно оставить или удалить.

Параметры вебхука поддерживают пользовательские макросы, все макросы, поддерживаемые в уведомлениях о проблемах, а также дополнительно макросы {ALERT.SENDTO}, {ALERT.SUBJECT} и {ALERT.MESSAGE}.

Если вы указываете HTTP-прокси, поле поддерживает ту же функциональность, что и поле HTTP proxy в настройке элемента данных. Строка прокси может иметь префикс [scheme]:// для указания типа используемого прокси (например, https, socks4, socks5; см. документацию).
Скрипт Введите код JavaScript в модальном редакторе, который открывается при нажатии на поле параметра или на значок карандаша рядом с ним. Этот код будет выполнять операцию вебхука.
Скрипт представляет собой код функции, принимающей пары параметр-значение. Значения должны быть преобразованы в объекты JSON с помощью метода JSON.parse(), например: var params = JSON.parse(value);.

Код имеет доступ ко всем параметрам, может выполнять HTTP-запросы GET, POST, PUT и DELETE, поддерживает дополнительные методы, такие как CONNECT, PATCH, HEAD, OPTIONS и TRACE, а также позволяет управлять HTTP-заголовками и телом запроса.
Скрипт должен содержать оператор return, иначе он будет недействительным. Он может возвращать статус OK вместе с необязательным списком тегов и значений тегов (см. параметр Обрабатывать теги) либо строку ошибки.

События восстановления (созданные автоматически или в результате ручного закрытия) создаются сервером и включают теги разрешённого события (включая теги, унаследованные от шаблонов, узлов сети и триггеров). Скрипты вебхуков выполняются после создания оповещения; поэтому теги, возвращаемые скриптом вебхука, добавляются только после первоначального создания оповещения и не будут присутствовать в макросах {EVENT.TAGS} и {EVENT.RECOVERY.TAGS} исходного сообщения о проблеме или немедленного сообщения о восстановлении.
Примечание: Рекомендуется использовать локальные переменные (например, var local = 1) вместо глобальных (например, global = 1), чтобы каждый скрипт работал со своими собственными данными и чтобы избежать конфликтов между одновременными вызовами (см. известные проблемы).

См. также: Рекомендации по разработке вебхуков, Примеры скриптов вебхуков, Дополнительные объекты JavaScript.
Тайм-аут Тайм-аут выполнения JavaScript (1-60s, по умолчанию 30s).
Поддерживаются суффиксы времени, например 30s, 1m.
Обрабатывать теги Установите флажок, чтобы обрабатывать значения возвращаемых свойств JSON как теги. Эти теги добавляются к любым существующим тегам проблемы.
Обратите внимание, что при использовании тегов вебхука вебхук должен возвращать объект JSON, содержащий как минимум пустой объект tags: var result = {tags: {}};
Примеры тегов, которые могут быть возвращены: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Включить запись в меню события Установите флажок, чтобы добавить запись в меню события со ссылкой на созданный внешний тикет.
Запись будет добавлена для каждого вебхука, который включён и для которого установлен этот флажок. Обратите внимание, что если параметры Имя записи меню и URL записи меню содержат какие-либо макросы {EVENT.TAGS.<tag name>}, запись будет добавлена только в том случае, если эти макросы могут быть разрешены (то есть если для события определены эти теги).
Если этот параметр отмечен, вебхук не следует использовать для отправки уведомлений разным пользователям (вместо этого рассмотрите возможность создания выделенного пользователя); также его не следует использовать в нескольких действиях оповещений для одного события проблемы.
Имя записи меню Укажите имя записи меню.
Поддерживается макрос {EVENT.TAGS.<tag name>}.
Это поле является обязательным только в том случае, если отмечен параметр Включить запись в меню события.
URL записи меню Укажите URL записи меню.
Поддерживается макрос {EVENT.TAGS.<tag name>}.
Это поле является обязательным только в том случае, если отмечен параметр Включить запись в меню события.

Подробные сведения о настройке сообщений по умолчанию и параметров обработки оповещений см. в разделе общие параметры способа оповещения.

Даже если вебхук не использует сообщения по умолчанию, шаблоны сообщений для типов операций, используемых этим вебхуком, всё равно должны быть определены.

Тестирование

Чтобы протестировать настроенный медиа-тип вебхука:

  1. Найдите соответствующий вебхук в списке медиа-типов.
  2. Нажмите Тест в последнем столбце списка (откроется окно тестирования).
  3. При необходимости измените значения параметров вебхука. Замените макросы примерами значений; в противном случае макросы не будут разрешены, и тест завершится ошибкой.
  4. Нажмите Тест.

Замена или удаление значений в окне тестирования влияет только на процедуру тестирования; фактические значения атрибутов вебхука останутся без изменений.

Чтобы просмотреть записи журнала тестирования медиа-типа, не покидая окно тестирования, нажмите Открыть журнал (откроется новое всплывающее окно).

Если тест вебхука выполнен успешно:

  • Отображается сообщение "Media type test successful.".
  • Ответ сервера отображается в сером поле Response.
  • Тип ответа (JSON или String) указывается под полем Response.

Если тест вебхука завершился неудачей:

  • Отображается сообщение "Media type test failed.", за которым следуют дополнительные сведения о сбое.

Пользовательские медиа

После настройки типа медиа перейдите в раздел Users > Users и назначьте медиа вебхука существующему пользователю или создайте нового пользователя, который будет представлять вебхук. Шаги по настройке пользовательских медиа для существующего пользователя, общие для всех типов медиа, описаны на странице Типы медиа.

Если вебхук использует теги для хранения ID заявки\сообщения, не назначайте один и тот же вебхук в качестве медиа разным пользователям, так как это может вызвать ошибки вебхука (это относится к большинству вебхуков, использующих опцию Include event menu entry). В этом случае рекомендуется создать отдельного пользователя, который будет представлять вебхук:

  1. После настройки типа медиа вебхука перейдите в раздел Users > Users и создайте отдельного пользователя Zabbix, который будет представлять вебхук — например, с именем пользователя Slack для вебхука Slack. Все настройки, кроме медиа, можно оставить по умолчанию, так как этот пользователь не будет входить в Zabbix.
  2. В профиле пользователя перейдите на вкладку Media и добавьте вебхук, указав необходимую контактную информацию. Если вебхук не использует поле Send to, введите любую комбинацию поддерживаемых символов, чтобы обойти требования проверки.
  3. Предоставьте этому пользователю как минимум права на чтение для всех узлов сети, для которых он должен отправлять оповещения, permissions.

При настройке действия оповещения добавьте этого пользователя в поле Send to users в сведениях об операции — это укажет Zabbix использовать вебхук для уведомлений из этого действия.

Настройка действий оповещений

Действия определяют, какие уведомления должны отправляться через вебхук. Шаги по настройке действий с использованием вебхуков такие же, как и для всех остальных типов средств оповещения, за исключением следующих случаев:

  • Если вебхук использует теги вебхука для хранения ID заявки\сообщения и обработки операций обновления\решения, избегайте использования одного и того же вебхука в нескольких действиях оповещений для одного события проблемы. Если {EVENT.TAGS.<tag name>} существует и обновляется в вебхуке, его итоговое значение будет неопределённым. Чтобы избежать этого, используйте в вебхуке новое имя тега для хранения обновлённых значений. Это относится к вебхукам Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad и Zendesk, предоставляемым Zabbix, а также к большинству вебхуков, использующих опцию Include event menu entry. Однако обратите внимание, что один вебхук можно использовать в нескольких операциях или шагах эскалации одного и того же действия, а также в разных действиях, которые не будут запускаться одним и тем же событием проблемы благодаря различным условиям.
  • При использовании вебхука в действиях для внутренних событий обязательно установите флажок Custom message и задайте пользовательское сообщение в конфигурации операции действия. В противном случае уведомление не будет отправлено.