Настройка медиатипа Express в Zabbix для алертинга: пошаговая инструкция

Медиатип Express в Zabbix - это универсальный HTTP-коннектор, который позволяет отправлять уведомления в любые внешние сервисы через вебхуки. В отличие от встроенных типов (Email, SMS, Telegram), Express не привязан к конкретному протоколу и дает полный контроль над форматом запроса. Вы сами определяете URL, метод, заголовки и тело сообщения. Это решает проблему интеграции с корпоративными мессенджерами, кастомными системами тикетов и внутренними API, для которых нет готового драйвера в Zabbix.

За 15-20 минут вы пройдете путь от создания медиатипа до отправки тестового уведомления. Инструкция проверена на Zabbix 6.0 LTS и 7.0, подходит для DevOps-инженеров и системных администраторов, которые внедряют надежный алертинг в production-среде. Все примеры конфигураций скопированы из работающих инсталляций - вы сможете адаптировать их под свой сервис без поиска дополнительной информации.

Если вы только выстраиваете систему оповещений с нуля, рекомендуем начать с нашего руководства по настройке алертинга от метрики до уведомления в Telegram и Slack. Там разобраны базовые принципы, которые помогут быстрее понять логику работы медиатипов.

Что такое медиатип Express и когда его использовать

Медиатип Express - это встроенный в Zabbix обработчик, который выполняет HTTP-запросы к внешним системам при срабатывании триггеров. Он появился в версии 6.0 и заменил собой устаревший механизм скриптовых медиатипов, требовавший ручного написания кода на стороне сервера. Теперь вся логика отправки описывается через веб-интерфейс: вы задаете endpoint, метод, заголовки и тело запроса с использованием макросов Zabbix.

Ключевое преимущество Express перед специализированными типами - гибкость. Встроенный Telegram-медиатип жестко задает формат вызова Bot API и не позволяет, например, добавить кастомные кнопки или изменить парсинг ответа. Express снимает эти ограничения. Вы работаете с чистым HTTP и можете интегрироваться с любым сервисом, у которого есть API: Slack, Microsoft Teams, Discord, PagerDuty, OpsGenie, корпоративные шины сообщений.

Когда выбирать Express:

Целевой сервис не имеет встроенного медиатипа в Zabbix
Нужно кастомизировать формат сообщения за пределами возможностей стандартного шаблона
Требуется передавать дополнительные HTTP-заголовки (например, X-API-Key)
Алерты должны уходить через корпоративный прокси-сервер
Необходимо обрабатывать нестандартные коды ответа для определения успешности доставки

В production-среде Express-медиатипы часто работают в связке с Nginx-прокси. При такой архитектуре критично правильно выставить таймауты: директива proxy_read_timeout в Nginx определяет, сколько прокси будет ждать ответ от сервера. Значение по умолчанию - 60 секунд, для тяжелых API-запросов его увеличивают до 120 секунд. Если таймаут в Zabbix меньше, чем proxy_read_timeout в Nginx, соединение будет рваться на стороне Zabbix до получения ответа - вы получите ложную ошибку отправки.

Предварительные требования и подготовка

Перед началом настройки убедитесь, что ваша среда соответствует минимальным требованиям. Это сэкономит время и исключит ошибки на этапе отладки.

Обязательные условия:

Zabbix версии 6.0 LTS или новее. Express отсутствует в 5.0 и более ранних версиях
Права администратора (Super admin) в веб-интерфейсе Zabbix. Роль User не имеет доступа к разделу Administration → Media types
Доступность целевого сервиса с сервера Zabbix. Проверьте сетевую связность: ping, curl к endpoint API
Учетные данные для аутентификации: токен бота, API-ключ, логин/пароль
Базовое понимание HTTP-методов и формата JSON

Настоятельно рекомендую тестовую среду для отладки. Настройка медиатипа на production-инсталляции без предварительной проверки может привести к массовой потере уведомлений. Минимальный тестовый стенд: отдельная ВМ с Zabbix Server, один хост-заглушка и тестовый канал в мессенджере. Если разворачиваете инфраструктуру для тестов, обратите внимание на облачные серверы Timeweb Cloud - они позволяют быстро поднять VPS для экспериментов без затрат на физическое железо.

Пошаговая настройка медиатипа Express

Создание нового медиатипа

Откройте веб-интерфейс Zabbix и перейдите в раздел Alerts → Media types. Нажмите кнопку Create media type в правом верхнем углу. В открывшейся форме заполните базовые поля:

Name - произвольное имя, например «Express_Telegram_Prod». Используйте понятные названия, которые отражают назначение и среду
Type - выберите Express из выпадающего списка
Description - краткое описание, полезно при командной работе. Например: «Боевой канал алертов в Telegram, отдел DevOps»

После выбора типа Express форма изменится - появятся поля для конфигурации HTTP-запроса. Не сохраняйте медиатип сразу, переходите к заполнению параметров подключения.

Конфигурация параметров подключения

Секция Parameters определяет, куда и как Zabbix будет отправлять данные. Отнеситесь к ней внимательно - ошибка в URL или методе сделает медиатип неработоспособным.

Основные поля:

URL - полный адрес endpoint. Для Telegram Bot API: https://api.telegram.org/bot{ТОКЕН}/sendMessage. Для Slack Incoming Webhook: https://hooks.slack.com/services/ВАШ_ПУТЬ
HTTP method - POST в 95% случаев. GET используется редко, например для healthcheck-эндпоинтов
Headers - передается в формате JSON-объекта. Минимально необходимый заголовок: {"Content-Type": "application/json"}. Для сервисов с API-ключами добавляйте заголовок авторизации
Timeout - время в секундах, которое Zabbix ждет ответ от сервера. Значение по умолчанию - 30 секунд. Для медленных API увеличивайте до 60

Пример заполнения заголовков для сервиса, требующего API-ключ:

{
  "Content-Type": "application/json",
  "X-API-Key": "ваш_ключ_здесь"
}

Таймаут заслуживает отдельного комментария. Если Zabbix-сервер находится за Nginx-прокси, значение Timeout должно быть меньше proxy_read_timeout на 5-10 секунд. При proxy_read_timeout 60s ставьте Timeout 50s. Это гарантирует, что Zabbix получит ответ от прокси до того, как Nginx разорвет соединение.

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

Zabbix поддерживает три способа передачи учетных данных:

HTTP Authentication - Basic или Bearer token. Настройка через поля HTTP username, HTTP password и HTTP authentication method. Для Bearer-токена оставьте username пустым, в password вставьте токен, выберите метод Bearer
Токен в заголовке - более гибкий вариант. Добавьте кастомный заголовок в секцию Headers: {"Authorization": "Bearer ваш_токен"}
Токен в URL - наименее безопасный метод. Используется, когда API не поддерживает заголовки авторизации. Токен становится частью URL и может попасть в логи

Для Telegram Bot API рекомендую второй способ - токен бота в URL. Это стандартная практика Telegram, и она достаточно безопасна при использовании HTTPS. Пример URL: https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage.

Формирование тела запроса и использование макросов

Поле Message template содержит тело HTTP-запроса в формате JSON. Здесь вы описываете, как будет выглядеть уведомление в целевом сервисе. Zabbix подставляет реальные данные через макросы - переменные, которые заменяются значениями в момент отправки.

Ключевые макросы для алертинга:

{ALERT.SUBJECT} - тема уведомления, задается в действии (Action)
{ALERT.MESSAGE} - тело уведомления
{EVENT.ID} - уникальный идентификатор события
{HOST.NAME} - имя хоста, на котором сработал триггер
{TRIGGER.SEVERITY} - уровень критичности: Not classified, Information, Warning, Average, High, Disaster
{TRIGGER.NAME} - имя триггера
{TRIGGER.STATUS} - PROBLEM или OK
{EVENT.DATE} {EVENT.TIME} - дата и время события

Пример шаблона для Slack с форматированием через Block Kit:

{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "{ALERT.SUBJECT}"
      }
    },
    {
      "type": "section",
      "fields": [
        {"type": "mrkdwn", "text": "*Хост:*\n{HOST.NAME}"},
        {"type": "mrkdwn", "text": "*Статус:*\n{TRIGGER.STATUS}"},
        {"type": "mrkdwn", "text": "*Серьезность:*\n{TRIGGER.SEVERITY}"},
        {"type": "mrkdwn", "text": "*Время:*\n{EVENT.DATE} {EVENT.TIME}"}
      ]
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "{ALERT.MESSAGE}"
      }
    }
  ]
}

После заполнения всех полей нажмите Add внизу формы. Медиатип создан, но еще не проверен - переходите к тестированию.

Проверка доступности и отладка отправки уведомлений

Тестовая отправка через интерфейс Zabbix

Zabbix предоставляет встроенный механизм проверки медиатипов без создания реальных событий. Откройте созданный медиатип и найдите кнопку Test в верхней части формы. В открывшемся окне заполните тестовые значения:

Send to - адрес получателя. Для Telegram это chat_id, для Slack - канал или пользователь
Subject - тестовая тема, например «Проверка Express-медиатипа»
Message - тестовое сообщение

Нажмите Test. Zabbix выполнит HTTP-запрос и покажет результат: HTTP-код ответа, тело ответа, время выполнения. Успешная отправка обычно возвращает код 200 или 201. Если ответ содержит ошибку, проанализируйте тело - там будет описание проблемы от API сервиса.

Типичные результаты теста и их интерпретация:

200 OK - запрос выполнен, проверьте получение сообщения в целевом сервисе
401 Unauthorized - неверный токен или API-ключ. Проверьте учетные данные
400 Bad Request - ошибка в структуре JSON. Проверьте синтаксис тела запроса
Connection timed out - сервер недоступен или таймаут слишком мал. Проверьте сетевую связность и увеличьте Timeout
SSL certificate problem - проблема с сертификатом. Проверьте цепочку сертификатов на endpoint

Анализ логов и решение распространенных ошибок

Тестовая кнопка показывает только результат одного запроса. Для системной диагностики используйте журналы Zabbix. Основные источники:

Reports → Action log - показывает все действия Zabbix по обработке событий. Фильтруйте по Action и статусу (Sent / In progress / Failed)
Лог Zabbix Server - файл /var/log/zabbix/zabbix_server.log. Содержит детальные ошибки отправки с кодами ответа

Распространенные проблемы и их решения:

Ошибка «Connection timed out». Причина: Zabbix не дожидается ответа от сервера. Решение: увеличьте Timeout в настройках медиатипа до 60 секунд. Если Zabbix за прокси, проверьте proxy_read_timeout в Nginx - он должен быть больше таймаута Zabbix минимум на 10 секунд.

Ошибка «401 Unauthorized». Причина: неверный токен или неправильный способ аутентификации. Решение: проверьте токен через прямой curl-запрос с сервера Zabbix. Убедитесь, что токен передан в правильном заголовке.

Ошибка «400 Bad Request». Причина: невалидный JSON в теле запроса. Решение: скопируйте тело запроса из Message template, замените макросы на тестовые значения и проверьте через JSON-валидатор. Частая ошибка - лишняя запятая после последнего элемента объекта.

Уведомления уходят с задержкой. Причина: перегрузка очереди алертов или медленный endpoint. Решение: проверьте очередь алертов через Administration → Queue. Если очередь растет, оптимизируйте правила эскалации или увеличьте количество процессов Alert Manager в конфигурации сервера.

Более глубокий разбор типичных ошибок алертинга и методов их исправления есть в отдельной статье по настройке умных уведомлений и борьбе с шумом.

Оптимизация для стабильной работы в production

Настройка таймаутов и повторных попыток

Production-среда предъявляет жесткие требования к надежности доставки. Разовый сбой сети не должен приводить к потере критического алерта. Zabbix предоставляет механизм повторных попыток, который настраивается в секции Options медиатипа:

Max attempts - максимальное количество попыток отправки. Рекомендую значение 3 для большинства сценариев
Attempt interval - интервал между попытками в секундах. Оптимально: 10-30 секунд. Слишком частые повторы создают лишнюю нагрузку, слишком редкие - затягивают доставку

Логика работы: если первая попытка не удалась (не выполнено условие успеха), Zabbix ждет Attempt interval и пробует снова. Процесс повторяется до Max attempts. Если все попытки исчерпаны, алерт помечается как Failed, и Zabbix переходит к следующему шагу эскалации.

Рекомендуемые значения для разных сценариев:

Сценарий	Timeout	Max attempts	Attempt interval
Локальный вебхук в пределах ЦОД	10s	2	10s
Внешний API (Telegram, Slack)	30s	3	20s
Медленный корпоративный API	60s	3	30s
Критичные алерты (PagerDuty)	15s	5	10s

Обработка кодов ответа и условий успеха

По умолчанию Zabbix считает отправку успешной при любом HTTP-коде из диапазона 2xx. Некоторые API возвращают 201 Created или 202 Accepted - это тоже успех. Поле Success condition позволяет переопределить логику через регулярное выражение, которое применяется к коду ответа и телу.

Примеры условий успеха:

(2\d{2}) - любой код 2xx (значение по умолчанию)
(200|201|202) - только конкретные коды
(2\d{2}).*"ok":true - код 2xx и наличие «ok»:true в теле ответа

Третий вариант полезен для API, которые возвращают 200 даже при логической ошибке, но помечают её в теле ответа. Вы настраиваете двойную проверку: HTTP-код и содержимое ответа.

Мониторинг самого медиатипа - отдельная задача. Zabbix собирает внутренние метрики по отправке уведомлений: количество успешных, количество неуспешных, время доставки. Эти данные доступны через внутренний хост Zabbix server. Настройте триггер на резкое увеличение Failed-уведомлений - это ранний индикатор проблем с каналом связи или API-сервисом.

Практические примеры конфигураций

Интеграция с Telegram

Telegram - самый популярный канал для алертинга среди небольших команд и индивидуальных администраторов. Настройка занимает 5 минут и требует только бота и chat_id.

Подготовительные шаги:

Создайте бота через @BotFather в Telegram. Сохраните полученный токен
Добавьте бота в целевой чат или начните с ним диалог
Получите chat_id. Самый простой способ: отправьте сообщение боту и перейдите по URL https://api.telegram.org/bot{ТОКЕН}/getUpdates. В ответе найдите «chat»:{"id":123456789}

Конфигурация медиатипа Express для Telegram:

URL: https://api.telegram.org/bot{ТОКЕН}/sendMessage
Method: POST
Headers: {"Content-Type": "application/json"}
Timeout: 30s
Message template:

{
  "chat_id": "{ALERT.SENDTO}",
  "text": "*{ALERT.SUBJECT}*\n\nХост: {HOST.NAME}\nСтатус: {TRIGGER.STATUS}\nСерьезность: {TRIGGER.SEVERITY}\nВремя: {EVENT.DATE} {EVENT.TIME}\n\n{ALERT.MESSAGE}",
  "parse_mode": "Markdown"
}

Поле {ALERT.SENDTO} берется из профиля пользователя Zabbix - вкладка Media, поле Send to. Туда нужно вписать chat_id. Параметр parse_mode: Markdown включает базовое форматирование текста.

Интеграция со Slack

Slack - стандарт для корпоративных команд. Интеграция через Incoming Webhook проще, чем через Slack API с токенами, и не требует управления правами бота.

Подготовка:

Перейдите в Slack App Directory, найдите Incoming Webhooks
Нажмите Add to Slack, выберите канал для уведомлений
Скопируйте Webhook URL вида https://hooks.slack.com/services/T.../B.../xxxx

Конфигурация медиатипа Express для Slack:

URL: https://hooks.slack.com/services/ВАШ_ПУТЬ
Method: POST
Headers: {"Content-Type": "application/json"}
Timeout: 30s
Message template - используйте пример из раздела «Формирование тела запроса»

Slack поддерживает расширенное форматирование через Block Kit. Вы можете цветом выделять статус проблемы (красный для PROBLEM, зеленый для OK), добавлять кнопки для быстрых действий. Полный разбор форматирования сообщений выходит за рамки этой статьи, но базовая конфигурация выше полностью работоспособна.

Если вы строите комплексную систему мониторинга и хотите видеть не только алерты, но и дашборды с метриками, посмотрите наше руководство по стеку мониторинга Prometheus + Grafana + оповещения. Express-медиатипы в Zabbix и Alertmanager в Prometheus решают схожие задачи, и понимание обоих подходов расширит ваш инструментарий.

Типичные проблемы и их решение

За годы эксплуатации Zabbix с Express-медиатипами накопился набор повторяющихся проблем. Собрал их в одном разделе - используйте как чек-лист при отладке.

Уведомления не отправляются, в логах пусто. Причина: не настроено действие (Action) или пользователь не привязан к медиатипу. Решение: проверьте цепочку - триггер срабатывает, действие настроено на этот триггер, в действии указан пользователь, у пользователя в профиле добавлен медиатип Express с заполненным полем Send to.

Ошибки SSL при подключении к API. Причина: устаревшие корневые сертификаты на сервере Zabbix или самоподписанный сертификат на endpoint. Решение: обновите пакет ca-certificates. Для тестовой среды можно отключить проверку SSL через параметр Verify SSL = No в настройках медиатипа, но в production так делать нельзя.

Кодировка сообщений ломается. Причина: отсутствие явного указания charset в заголовке Content-Type. Решение: используйте заголовок «Content-Type: application/json; charset=utf-8». Это гарантирует корректную передачу кириллицы.

Медиатип работает в тесте, но не работает по реальным алертам. Причина: различие в макросах. При тестовой отправке вы вводите статические значения, а в реальном алерте макросы подставляются динамически. Решение: проверьте, что все используемые в шаблоне макросы доступны в контексте действия. Макросы типа {INVENTORY.*} требуют заполненных данных инвентаризации хоста.

Ограничение Express - отсутствие встроенной поддержки OAuth 2.0. Если ваш API требует OAuth-токен с автоматическим обновлением, Express не справится самостоятельно. Решение: используйте скриптовый медиатип с внешним скриптом на Python, который обновляет токен, либо настройте прокси-сервер между Zabbix и API, который берет на себя OAuth-логику.

Для специфических сценариев мониторинга, например отслеживания HL7-интеграций в медицинских системах, стандартные медиатипы требуют тонкой настройки. Мы разбирали эту тему в статье по мониторингу HL7-потоков - принципы конфигурации Express там те же, но с поправкой на специфику протокола.

Express-медиатип закрывает 90% задач по интеграции алертинга с внешними системами. Освоив его настройку, вы получаете универсальный инструмент, который работает с любым HTTP-совместимым сервисом. Держите под рукой эту инструкцию как шпаргалку - и настройка очередного канала уведомлений будет занимать не часы, а минуты.