Перейти к основному содержимому

Документация

Полное руководство по настройке мониторинга сайтов с PingZen. Документация API, примеры кода и лучшие практики.

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

PingZen поддерживает множество каналов оповещений. Настройте один или несколько каналов для резервирования.

Telegram

Самый быстрый способ получения уведомлений (1-2 секунды). Настройка в одно нажатие.

  1. В PingZen перейдите в Оповещения → Создать оповещение → выберите Telegram
  2. Нажмите «Подключить Telegram» — ссылка на @pingzen_bot откроется автоматически
  3. Нажмите Start в Telegram — аккаунт привяжется мгновенно
  4. Для групповых алертов: переключитесь на вкладку «Групповой чат» и нажмите «Добавить бота в группу»

Копировать Chat ID вручную не нужно — мастер сделает всё автоматически. При необходимости можно ввести Chat ID вручную.

Slack

Интеграция через Incoming Webhooks для командной работы.

  1. В Slack перейдите в Settings → Apps → Incoming Webhooks
  2. Нажмите 'Add New Webhook to Workspace'
  3. Выберите канал для уведомлений
  4. Скопируйте Webhook URL (https://hooks.slack.com/...)
  5. В PingZen создайте оповещение и вставьте URL

Создайте отдельный канал #alerts для оповещений о мониторинге.

Discord

Настройка в одно нажатие через OAuth или вставка Webhook URL.

  1. В PingZen перейдите в Оповещения → Создать оповещение → выберите Discord
  2. Нажмите «Connect Discord» — вы будете перенаправлены в Discord
  3. Выберите сервер и канал, затем подтвердите авторизацию
  4. Вы вернётесь в PingZen — вебхук сохранится автоматически

Можно также вставить Webhook URL вручную. Создайте его в Discord: Server Settings → Integrations → Webhooks.

Microsoft Teams

Отправка оповещений в каналы Microsoft Teams через Incoming Webhook.

  1. 1.В Teams выберите канал → More options → Connectors
  2. 2.Найдите 'Incoming Webhook' и нажмите Configure
  3. 3.Дайте имя вебхуку и скопируйте URL
  4. 4.В PingZen создайте оповещение типа MS Teams
  5. 5.Вставьте Webhook URL

Mattermost

Slack-совместимые вебхуки для self-hosted команд.

  1. В Mattermost: Main Menu → Integrations → Incoming Webhooks
  2. Нажмите Add Incoming Webhook
  3. Выберите канал и скопируйте Webhook URL
  4. В PingZen используйте тип Mattermost

WhatsApp

Получайте оповещения через WhatsApp с помощью Twilio API.

  1. Создайте аккаунт Twilio и настройте WhatsApp Business API
  2. Получите Twilio Account SID, Auth Token и номер WhatsApp
  3. В PingZen создайте оповещение типа WhatsApp
  4. Введите ваш номер WhatsApp (с кодом страны, например +79001234567)

Для WhatsApp-уведомлений необходим аккаунт Twilio с активированным WhatsApp Business API.

PagerDuty

Маршрутизация алертов в PagerDuty для эскалации дежурным.

  1. В PagerDuty перейдите Services → Service Directory → выберите сервис
  2. Вкладка Integrations → Add Integration → Events API v2
  3. Скопируйте Integration Key (routing key)
  4. В PingZen создайте PagerDuty алерт и вставьте routing key

PagerDuty создаёт настоящие инциденты с эскалацией — идеально для продакшн-сервисов.

Push-уведомления в браузере

Мгновенные push-уведомления прямо в браузере — без приложений и расширений.

  1. Перейдите в Настройки → Уведомления в PingZen
  2. Нажмите «Включить push-уведомления»
  3. Разрешите уведомления когда браузер запросит разрешение
  4. Алерты будут доставляться даже когда PingZen не открыт

Push-уведомления работают в Chrome, Firefox и Edge. Требуется HTTPS.

Email

Надёжная доставка email через Resend. Никакой настройки с вашей стороны — достаточно указать email-адрес.

  1. В PingZen откройте Алерты → Создать алерт → выберите Email
  2. Укажите email получателя (личный, командный или рассылка)
  3. Сохраните алерт — тестовая доставка автоматически уходит с alerts@alerts.pingzen.dev
  4. Проверьте почту (включая «Спам» при первой доставке) чтобы убедиться что дошло

Отправляем с выделенного субдомена alerts.pingzen.dev с настроенными SPF/DKIM/DMARC — письма стабильно попадают во Входящие. Заголовок List-Unsubscribe даёт Gmail кнопку быстрой отписки.

Webhook

Отправка JSON данных на ваш HTTP эндпоинт для кастомных интеграций (Home Assistant, n8n, Node-RED, IFTTT, собственные сервисы).

  1. Создайте HTTP эндпоинт на вашем сервере для приёма POST запросов
  2. В PingZen создайте оповещение типа Webhook
  3. Укажите URL вашего эндпоинта
  4. Метод запроса — POST, заголовок Content-Type: application/json, User-Agent: PingZen-Alert-Service/1.0
💡

Привязали один вебхук к нескольким мониторам? См. разделы «Один вебхук для нескольких мониторов», «Пример Home Assistant» или «Пример ntfy.sh» ниже — там готовые рецепты с роутингом по ID монитора.

Формат JSON данных

POST <ваш URL>
Content-Type: application/json
User-Agent: PingZen-Alert-Service/1.0

{
  "text": "🔴 My Website - Service Down",
  "body": "URL: https://example.com\nProtocol: HTTPS\nStatus: DOWN\nResponse Time: 5000ms\n\nOpen monitor: https://pingzen.dev/monitors/123?ws=4",
  "priority": "critical",
  "timestamp": "2026-04-22T10:30:00+00:00",
  "source": "pingzen",
  "monitor_url": "https://pingzen.dev/monitors/123?ws=4",
  "monitor_id": 123,
  "monitor_name": "My Website",
  "trigger": "down",
  "status": "down",
  "probes": [
    {"label": "Moscow", "status": "up", "fail_streak": 0},
    {"label": "Istanbul", "status": "down", "fail_streak": 3}
  ]
}

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

URL: https://example.com
Protocol: HTTPS
Status: DOWN
Response Time: 5000ms

Open monitor: https://pingzen.dev/monitors/123?ws=4

Поля payload

FieldDescription
textЗаголовок: эмодзи + имя монитора + локализованный статус ("Service Down" / "Сервис недоступен", "Service Recovered" / "Сервис восстановлен", "Service Degraded", "Certificate Expiring" и т.д.). Эмодзи: 🔴 DOWN/STILL_DOWN, 🟢 RECOVERED, 🟡 DEGRADED, ⚠️ CERTIFICATE_EXPIRING.
bodyМногострочное тело: URL, Protocol, Status (значение enum в верхнем регистре: DOWN/UP/DEGRADED) либо Error, Response Time, HTTP Status, Open monitor. Префиксы и сами слова статуса локализованы под язык монитора. Состав полей настраивается в форме оповещения в разделе «Содержимое сообщения».
priorityПриоритет события (НЕ локализован, безопасно использовать для роутинга): critical (DOWN, STILL_DOWN, CERTIFICATE_EXPIRING — корзина «реальных сбоев»), high (DEGRADED, RESPONSE_TIME_HIGH), normal (RECOVERED — восстановление). Фильтр priority == 'critical' ловит и сбои, и reminder'ы, не задевая degraded/медленный отклик.
timestampВремя события в формате ISO 8601 (UTC).
sourceВсегда "pingzen" — удобно фильтровать в обработчике, если на эндпоинт приходят события из разных источников.
monitor_urlСсылка на страницу монитора в PingZen. Содержит ID монитора в пути /monitors/{id}. ⚠️ Поле приходит только если в форме оповещения включена настройка «Ссылка на монитор» (включена по умолчанию).
monitor_idID монитора (целое число). Удобно для прямого роутинга — без regex'а из monitor_url. Не приходит для синтетических алертов (heartbeat).
monitor_nameИмя монитора без эмодзи и статуса (raw). То же самое, что зашито в text, но отдельным полем — удобно для шаблонов уведомлений.
triggerТип события (raw enum, НЕ локализован — лучший primitive для роутинга): down, still_down (повторное напоминание о DOWN), recovered, degraded, certificate_expiring, response_time_high.
statusТекущий статус монитора (raw enum, НЕ локализован): up, down, degraded, warning, transient, timeout, unknown. ⚠️ Для тестовой доставки (см. поле test) status содержит синтетическое значение check-результата, а не живой статус монитора — не привязывайте логику автоматизаций к этому полю. Используйте trigger.
testПрисутствует (и равно true) ТОЛЬКО для доставок, инициированных кнопкой «Тест» в UI. Production-алерты не содержат это поле. Обязательно фильтруйте тестовые доставки в любой автоматизации, меняющей состояние entities — см. пример Home Assistant ниже.
monitorsМассив `{id, name, status, last_check_at}` для КАЖДОГО монитора в alert. Приходит ТОЛЬКО в тестовых доставках (вместе с `test: true`). Позволяет HA / n8n автоматизациям ре-синхронизировать состояния ВСЕХ entities за один клик «Тест», вместо нажатия по разу на каждый монитор. Production-алерты не содержат этого поля — они описывают один check_result через top-level monitor_id/monitor_name/status.
probesМассив `{label, status, fail_streak}` по каждому назначенному чекеру — по одной записи на каждый из `monitor.probe_ids`. Приходит ТОЛЬКО для multi-probe мониторов (≥2 чекера). Single-probe и central-only мониторы это поле не содержат. В каждой записи: `label` — город чекера (например, «Istanbul»), `status` — статус проверки конкретно этого чекера (up/down/degraded/timeout/error/unknown — НЕ локализован), `fail_streak` — счётчик подряд идущих сбоев. Удобно для HA / n8n автоматизаций, маршрутизирующих по региону: `{% if probe.status == 'down' and probe.label == 'Istanbul' %}…`.

Один вебхук для нескольких мониторов

Вы можете привязать один и тот же вебхук URL к нескольким мониторам (или к одному оповещению, которое срабатывает на группу). Для роутинга используйте machine-readable поля: monitor_id (целое число) для определения монитора и trigger ("down" / "still_down" / "recovered" / "degraded" / "certificate_expiring") для типа события. Оба поля НЕ локализованы. Парсить text по подстроке "DOWN" не рекомендуется: text содержит локализованную фразу ("Service Down" / "Сервис недоступен"), а не сам токен "DOWN".

Пример: ntfy.sh

По умолчанию ntfy.sh показывает тело JSON-запроса как обычный текст, поэтому простой /<topic> покажет на телефоне сырой JSON. Используйте inline-шаблонизацию через query-параметры — PingZen передаёт URL без изменений, поэтому никакой прокси/мост не нужен. Таблица ниже показывает, какое поле PingZen превращается в какой параметр ntfy.

Маппинг полей
Поле PingZenПараметр ntfyКомментарий
monitor_name?t= (заголовок)Выводится жирным как заголовок уведомления.
body?m= (текст)Многострочный текст уведомления (URL + статус + время отклика).
trigger ("down" / "recovered" / …)?p= (приоритет 1–5)down / still_down → 5 (urgent), recovered → 3 (default), остальные → 4 (high). ntfy ждёт число, поэтому нужен Go-шаблон if/else.
trigger (как есть)?tags= (теги/эмодзи)ntfy сам подставит подходящие эмодзи (warning, white_check_mark).
Базовый рецепт
URL
https://ntfy.sh/my-pingzen-topic?template=yes&t={{.monitor_name}}&m={{.body}}&p={{if eq .trigger "down"}}5{{else if eq .trigger "still_down"}}5{{else if eq .trigger "recovered"}}3{{else}}4{{end}}&tags={{.trigger}}
Вставьте эту строку целиком в поле «URL вебхука» в PingZen. Замените my-pingzen-topic на своё название — ntfy создаёт топики на лету, поэтому случайная неугадываемая строка работает как пароль.
Что вы увидите на телефоне
MyAPInow

🔴 My Website - Service Down URL: https://example.com Статус: DOWN · 5000 мс

⚠️тег: down · приоритет: urgent
Self-hosted ntfy — меняется только хост
URL
https://ntfy.example.com/my-pingzen-topic?template=yes&t={{.monitor_name}}&m={{.body}}
Защищённый топик с access-токеном
URL
https://ntfy.sh/my-pingzen-topic?template=yes&t={{.monitor_name}}&m={{.body}}&auth=tk_AgQdq7mVBoFD37zQVxrGuMzfp3KuG

Пример: Home Assistant

Пример automation: использует monitor_id для роутинга по конкретному монитору и trigger для типа события (down / still_down / recovered). Все поля НЕ локализованы — работает одинаково для EN и RU мониторов.

# configuration.yaml — automations
# 1. Реальные алерты (DOWN / still_down / recovered / degraded …)
- alias: PingZen alert
  trigger:
    platform: webhook
    webhook_id: pingzen
    allowed_methods: [POST]
    local_only: false
  # ВАЖНО: пропускаем доставки от кнопки «Тест», чтобы они не меняли entities.
  # Тестовые payload содержат "test": true (production-алерты — без этого поля).
  condition:
    - "{{ trigger.json.test | default(false) == false }}"
  variables:
    monitor_id: "{{ trigger.json.monitor_id | int(0) }}"
    event:      "{{ trigger.json.trigger }}"   # down | still_down | recovered | degraded | certificate_expiring
  action:
    - choose:
        # Роутер: первый DOWN → мигнуть светом, повторные напоминания игнорируем
        - conditions: "{{ monitor_id == 123 and event == 'down' }}"
          sequence:
            - service: light.turn_on
              target: { entity_id: light.kitchen }
              data: { flash: short }
        # NAS: реагируем и на первый DOWN, и на повторные напоминания
        - conditions: "{{ monitor_id == 456 and event in ['down', 'still_down'] }}"
          sequence:
            - service: notify.mobile_app
              data:
                title: "{{ trigger.json.text }}"
                message: "{{ trigger.json.body }}"
        # Восстановление любого монитора → отметить в логе
        - conditions: "{{ event == 'recovered' }}"
          sequence:
            - service: logbook.log
              data:
                name: "PingZen"
                message: "{{ trigger.json.monitor_name }} восстановился"
      default:
        - service: persistent_notification.create
          data:
            title: "{{ trigger.json.text }}"
            message: "{{ trigger.json.body }}"

# 2. Sync state по клику «Тест» — итерирует массив monitors и приводит
#    каждый entity в соответствие с PingZen (полезно после рестарта HA
#    или когда состояния entities разъехались с реальностью).
- alias: PingZen sync from Test click
  trigger:
    platform: webhook
    webhook_id: pingzen
    allowed_methods: [POST]
    local_only: false
  # ТОЛЬКО для тестовых доставок с массивом monitors
  condition:
    - "{{ trigger.json.test | default(false) == true }}"
    - "{{ 'monitors' in trigger.json }}"
  action:
    - repeat:
        for_each: "{{ trigger.json.monitors }}"
        sequence:
          # Подгоните entity_id под свою схему именования
          - service: "{{ 'input_boolean.turn_on' if repeat.item.status == 'up' else 'input_boolean.turn_off' }}"
            target:
              entity_id: "input_boolean.pingzen_{{ repeat.item.id }}"

Подсказки

  • URL вебхука обязательно HTTPS (HTTP разрешён только для localhost — для локальной разработки).
  • Таймаут — 30 секунд, до 3 повторов с экспоненциальной задержкой при 5xx ошибках и сетевых сбоях. На ответы 401/403 повторов нет — проверьте права/секрет.
  • Для аутентификации по статичному токену добавьте секрет прямо в URL (например, ?token=...) — query-параметры сохраняются и приходят на ваш эндпоинт. Home Assistant и n8n поддерживают этот вариант из коробки.
  • Состав body настраивается в форме оповещения (раздел «Содержимое сообщения») — можно отключить любое поле, в т.ч. ссылку на монитор. Если отключите «Ссылка на монитор» — поле monitor_url исчезнет из payload.
  • Для роутинга используйте machine-readable поля (НЕ локализованы): monitor_id для определения монитора, trigger для типа события. Поле text локализовано — парсить его подстроками («DOWN», «UP») ненадёжно.
  • Reminder-уведомления (повторные алерты о DOWN-мониторе) приходят с trigger="still_down" и priority="critical" (та же корзина, что и первый DOWN — это и есть «реальный сбой»). Если хотите разную реакцию на первый DOWN и reminders — используйте trigger in ['down', 'still_down'].
  • Кнопка «Тест» в форме алерта отправляет payload с "test": true плюс префиксом [ТЕСТ] в text и строкой (Тестовое уведомление) в начале body. ВСЕГДА фильтруйте тестовые доставки в автоматизациях, меняющих состояние entities — см. блок condition в примере выше.
  • Для тестовых доставок status = "up" при trigger = "down" — это специально: синтетический check_result равен UP, но trigger симулирует самый частый путь алерта (DOWN). Не привязывайте логику автоматизации к body или status для тестовых событий — используйте trigger и поле test.

Триггеры оповещений

Выберите события, при которых отправляются уведомления:

DOWN

Сервис недоступен (DOWN)

Отправляется когда монитор переходит в статус DOWN после подтверждения (по умолчанию 3 последовательных ошибки).

UP

Восстановление (RECOVERED)

Отправляется когда монитор восстанавливается после падения.

DEGRADED

Деградация (DEGRADED)

Деградация сервиса (вкл. PageSpeed score ниже порога).

SSL

SSL истекает

Отправляется за 14 дней до истечения SSL сертификата.

Когда приходят оповещения

Триггеры в PingZen реагируют на смену состояния, а не на текущее состояние. Это главный источник недопонимания, когда дашборд показывает «Critical», а уведомления не приходят.

Без «Напоминать пока недоступен»

10:00  монитор уходит в DOWN     → 1× оповещение DOWN
10:01 — следующий день           → тишина (всё ещё DOWN, перехода нет)
следующий день  восстановление   → 1× оповещение RECOVERED

Если монитор стоит DOWN 5 дней подряд, вы получите ровно два сообщения — одно в начале, одно в конце.

С включённым «Напоминать пока недоступен»

10:00  DOWN                        → 1× DOWN
10:05  всё ещё DOWN                → STILL_DOWN (ступень 5 мин)
10:20  всё ещё DOWN                → STILL_DOWN (15 мин)
11:20  всё ещё DOWN                → STILL_DOWN (1 час)
15:20, 19:20, 23:20, …             → STILL_DOWN каждые 4 часа
восстановление                     → 1× RECOVERED, расписание сбрасывается

Лестница эскалации сбрасывается каждый раз, когда монитор восстанавливается и падает снова.

Частая ошибка

Если дашборд показывает «Critical», но оповещения не приходят — проверьте, что у этого оповещения включён переключатель «Напоминать пока недоступен». Триггер «Down» сам по себе срабатывает только в момент падения, не периодически.

Настройки сообщения

Настройте, какая информация включается в уведомления. По умолчанию большинство полей включены. Вы можете переключать каждое поле для каждого оповещения.

URL — адрес отслеживаемого эндпоинта
Протокол — HTTP, TCP, DNS и т.д.
Время отклика — длительность проверки в миллисекундах
HTTP статус-код — код ответа (например 200, 502)
Сообщение об ошибке — детали сбоя или причина таймаута
Информация об аккаунте — ваш email или имя аккаунта (по умолчанию отключено для приватности)
Длительность простоя — как долго монитор был недоступен (показывается только при восстановлении)
Ссылка на монитор — кликабельная ссылка, открывающая страницу монитора в PingZen
Откуда проверено — локация probe (город, страна, провайдер) или пометка «центральный» (по умолчанию отключено)

Отключите ненужные поля, чтобы уведомления были лаконичными. «Информация об аккаунте» отключена по умолчанию для приватности; «Откуда проверено» отключено по умолчанию, чтобы не шуметь тем, кто не использует внешние probes.

Оповещения для Heartbeat-мониторов

Оповещения работают как с обычными мониторами, так и с heartbeat-мониторами. При создании оповещения можно выбрать heartbeat-мониторы в секции «Heartbeat-мониторы» под списком обычных мониторов.

Одно оповещение может наблюдать одновременно за обычными и heartbeat-мониторами. Счётчик мониторов показывает общее количество обоих типов.

Напоминания

Включите переключатель «Напоминать пока недоступен» для получения периодических уведомлений пока монитор остаётся недоступным. Интервалы нарастают автоматически: 5 мин → 15 мин → 1 час → далее каждые 4 часа. Расписание сбрасывается при восстановлении.

Напоминания отключены по умолчанию. Включите их для критичных сервисов, где нужна постоянная эскалация — без этого переключателя падение, длящееся несколько дней, породит всего два сообщения (начальный DOWN и финальный RECOVERED).

Период ожидания (Cooldown)

Минимальное время между повторными оповещениями для одной проблемы. Предотвращает спам при нестабильном соединении. По умолчанию: 5 минут. Оповещения о восстановлении всегда игнорируют cooldown.

Рекомендуется: 5-15 минут для продакшн окружений.

История оповещений

Вкладка «История» на странице оповещений показывает лог всех отправленных уведомлений: время, тип триггера, канал, получатель и статус доставки (отправлено/ошибка). Неудачные доставки содержат детали ошибки.

Используйте историю для проверки доставки уведомлений и диагностики сбоев.

API для оповещений

Управляйте оповещениями программно через REST API.

GET/api/v1/alerts

Список оповещений

POST/api/v1/alerts

Создать оповещение

PATCH/api/v1/alerts/:id

Обновить оповещение

DELETE/api/v1/alerts/:id

Удалить оповещение

POST/api/v1/alerts/:id/test

Тест оповещения

Частые вопросы

Какие протоколы можно мониторить?

PingZen поддерживает 23 протокола: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, SSL сертификаты, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check и Transaction. Вы можете мониторить сайты, API, серверы, базы данных и любые сетевые сервисы.

Как быстро приходят оповещения?

Telegram оповещения доставляются в течение 1-2 секунд после обнаружения. Slack и Discord уведомления приходят практически мгновенно. Вы можете настроить несколько каналов оповещений для резервирования.

Можно ли организовать мониторы по проектам?

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

Есть ли API для автоматизации?

Абсолютно. PingZen предоставляет полный REST API с OpenAPI документацией. Вы можете создавать, обновлять и удалять мониторы программно.

Как работают статус-страницы?

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

Что происходит, если я достигну лимита мониторов?

Мы уведомим вас при приближении к лимиту. Вы можете приостановить некоторые мониторы или связаться с нами для увеличения лимита. Мы никогда не останавливаем мониторинг без предупреждения, обеспечивая защиту ваших критически важных сервисов.

Готовы перестать пропускать даунтаймы?

Присоединяйтесь к тысячам команд, которые доверяют PingZen. Настройка за 30 секунд.