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. Нажмите Создать тип оповещения.

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

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

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

Parameter Description
Parameters Укажите переменные вебхука в виде пар атрибутов и значений.
Для преднастроенных вебхуков список параметров зависит от сервиса. Смотрите описание параметров в файле 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; см. документацию).
Script Введите код JavaScript в модальном редакторе, который открывается при щелчке в поле параметра или по значку карандаша рядом с ним. Этот код будет выполнять операцию вебхука.
Код представляет собой функцию, принимающую пары параметр - значение. Значения следует преобразовывать в объекты JSON с помощью метода JSON.parse(), например: var params = JSON.parse(value);.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При настройке действия для оповещений добавьте этого пользователя в поле 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 и задайте пользовательское сообщение в конфигурации операции действия. В противном случае уведомление не будет отправлено.