Интеграция вебхуков - полное руководство по HTTP-триггерам

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

Что такое вебхук

Вебхук — это способ для одного приложения передавать другим приложениям информацию в реальном времени через HTTP-вызовы. Считайте его номером телефона, который вы кому-то даёте: когда по этому номеру звонят, ваш телефон звонит. В цифровом мире, когда в одной системе что-то происходит (высокая загрузка CPU, упавшая сборка, новый заказ), она отправляет HTTP-запрос на предоставленный вами URL (вебхук), и это запускает действие в вашей системе.

Например, когда загрузка CPU вашего сервера становится слишком высокой, система мониторинга может обратиться к URL вебхука Echobell, а тот запустит уведомление, чтобы вас предупредить. Это происходит автоматически и в реальном времени, без того чтобы вы сами постоянно следили за загрузкой CPU.

Вебхуки — основа событийно-ориентированных архитектур; их поддерживают практически все современные облачные сервисы, инструменты мониторинга и SaaS-платформы. Они легковесны, быстры и не требуют от вас никакой особой инфраструктуры — достаточно HTTP-клиента.

Преимущества вебхуков

Реальное время: события запускают уведомления мгновенно, обычно за 1–2 секунды
Универсальность: поддерживаются почти всеми современными сервисами и языками программирования
Гибкость: передавайте свои данные, чтобы получать содержательные уведомления с контекстом
Надёжность: работают поверх HTTP, со стандартными кодами статуса и обработкой ошибок
Масштабируемость: опрос не нужен — уведомления отправляются только тогда, когда происходят события

Обзор

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

Формат URL вебхука

https://hook.echobell.one/t/{channel-token}

URL вебхука своего канала вы найдёте в подробностях канала в приложении Echobell.

Отправка запросов к вебхуку

Вебхуки Echobell поддерживают методы GET и POST:

GET-запрос

Переменные можно передавать через параметры строки запроса:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

POST-запрос

В POST-запросах переменные передаются в теле JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Только POST

У каждого канала в приложении Echobell есть переключатель Только POST в разделе Расширенные настройки. По умолчанию он выключен.

Когда он включён, запустить канал можно только запросом POST. Запрос GET к URL вебхука отклоняется с 405 Method Not Allowed, и уведомление не отправляется:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Запросов HEAD это не касается: они отвечают 200 и никогда не запускают уведомление независимо от того, включена настройка «Только POST» или нет.

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

Специальные переменные

Echobell поддерживает специальную переменную, которая добавляет уведомлениям возможности:

externalLink: если передать её в запросе, в списке записей уведомлений появится кликабельная ссылка. Удобно, чтобы вести к подробностям или связанным ресурсам.

Пример с внешней ссылкой:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Переменные шаблона

Переменные, переданные через вебхук, можно использовать в шаблонах уведомлений с помощью синтаксиса {{variableName}}:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

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

Системные переменные времени (UTC)

Помимо данных, которые вы отправляете, Echobell предоставляет системные переменные времени только для чтения — они всегда доступны в шаблонах и условиях. Все значения вычисляются в UTC. Плоские поля: date, time, year, month, dayOfWeek, hour, minute и second. Остальные — такие как sys.dayOfWeekName, sys.epochMs и sys.epochSeconds — доступны только в пространстве имён sys.. Полный список и примеры см. в разделе Условия.

Частые сценарии использования

Вебхуки — самый популярный способ запуска в Echobell, и особенно они полезны для:

DevOps и мониторинг

Мониторинг серверов: оповещения о загрузке CPU, памяти и диска из систем мониторинга вроде Prometheus или Grafana
Мониторинг доступности: оповещения о доступности сайтов и сервисов из Uptime Kuma или UptimeRobot
Мониторинг контейнеров: сбои Docker, падения подов Kubernetes и нехватка ресурсов
Агрегация логов: критические ошибки и исключения из систем управления логами

Разработка и CI/CD

Уведомления о сборках: упавшие сборки, результаты тестов, статус развёртывания из GitHub Actions или GitLab CI
Качество кода: ошибки линтера, уязвимости, изменения покрытия тестами
События репозитория: пул-реквесты, коммиты, релизы и активность соавторов
Отслеживание развёртываний: успешные деплои, откаты и изменения окружений

Бизнес-приложения

Электронная коммерция: новые заказы, подтверждения оплаты, предупреждения об остатках, статусы доставки
CRM: новые лиды, закрытые сделки, обращения в поддержку, взаимодействия с клиентами
Обработка платежей: завершённые транзакции, запросы на возврат, оповещения о мошенничестве
Отправка форм: формы обратной связи, ответы на опросы, завершённые регистрации

IoT и умный дом

События умного дома: датчики дверей, детекция движения, изменения температуры через Home Assistant
IoT-устройства: показания датчиков, изменения статуса устройств, проблемы со связью
Системы безопасности: срабатывания сигнализации, движение в кадре камеры, события контроля доступа
Мониторинг среды: превышение порогов по температуре, влажности и качеству воздуха

Трейдинг и финансы

Рыночные оповещения: движения цен, технические индикаторы из TradingView
Мониторинг портфеля: изменения позиций, маржин-коллы, остатки на счетах
Экономические события: выход новостей, отчёты о прибыли, изменения настроений рынка

Инструкции по настройке для популярных платформ — в наших руководствах по интеграциям.

Конфиденциальность и безопасность

Как Echobell обращается с данными ваших вебхуков:

Что сохраняется

На наших серверах:
- URL вебхуков (токены) — нужны, чтобы направлять входящие запросы в каналы
- Настройки каналов — шаблоны, условия, параметры
- Связи подписок — какие пользователи подписаны на какие каналы
На вашем устройстве:
- Содержимое уведомлений — готовые заголовок и текст
- История запусков — когда уведомления были получены
- Значения переменных — данные, переданные в вызовах вебхука
- Ссылки и метаданные — externalLink и другие связанные данные

Что не сохраняется

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

Устранение неполадок

Если вебхуки работают не так, как вы ожидаете, попробуйте эти шаги диагностики:

Вебхук не запускает уведомления

Проверьте, что URL вебхука верный
- Скопируйте URL прямо из приложения Echobell
- Убедитесь, что не добавились лишние пробелы или символы
- Проверьте, что вы используете https://hook.echobell.one/t/, а не другой домен
Проверьте, активен ли канал
- Откройте канал в приложении Echobell
- Убедитесь, что он не удалён и не архивирован
- Проверьте, что вы не сбрасывали токен вебхука (это делает старый URL недействительным)
Убедитесь, что тело JSON оформлено корректно (для POST-запросов)
- Проверьте полезную нагрузку валидатором JSON
- Убедитесь, что строки заключены в кавычки
- Проверьте, что заголовок Content-Type установлен в application/json
Убедитесь, что переданы все переменные, которые нужны вашим шаблонам
- Посмотрите в шаблонах уведомлений, какие переменные они используют
- Проверьте, что эти переменные есть в запросе к вебхуку (в параметрах строки запроса или в теле JSON)
- Помните: отсутствующие переменные подставляются как пустые строки
Проверьте, есть ли у канала активные подписчики
- Уведомления отправляются, только если кто-то подписан на канал
- Проверьте свою подписку в списке каналов в приложении
- Убедитесь, что подписки не были случайно удалены

Уведомления отображаются неправильно

Имена переменных не совпадают
- В шаблоне используется {{server_name}}, а вебхук отправляет serverName
- Имена переменных чувствительны к регистру и должны совпадать точно
- Проверьте, нет ли опечаток в именах переменных
Вложенные данные недоступны
- Используйте точечную нотацию: {{user.name}} — или скобочную: {{user["name"]}}
- Проверьте, что структура вашего JSON соответствует ожиданиям шаблона
- Сначала попробуйте простые плоские переменные, затем добавляйте вложенность
Проблемы из-за специальных символов
- Корректно кодируйте параметры строки запроса
- Экранируйте специальные символы JSON в телах POST-запросов
- Сначала проверьте на простом ASCII-тексте

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

Проверьте вебхук напрямую с помощью curl:

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Если всё настроено правильно, уведомление придёт сразу.

Проблема осталась?

Если вы прошли шаги выше, а проблема сохраняется:

Загляните в центр поддержки за дополнительными руководствами по диагностике
Проверьте, нет ли известных проблем или сообщений о статусе сервиса
Напишите нам на echobell@weelone.com и приложите:
- Описание проблемы
- Шаги, которые вы уже попробовали
- Пример URL вебхука (с удалённым или скрытым токеном)
- Пример тела запроса
- Ожидаемое и фактическое поведение

Дальнейшие шаги

Теперь, когда вы разобрались с интеграцией вебхуков:

Изучите синтаксис шаблонов — создавайте динамичные и информативные уведомления
Используйте условия — фильтруйте уведомления по данным
Изучите интеграции — подключайтесь к инструментам, которыми вы уже пользуетесь
Настройте оповещения Grafana — мониторинг инфраструктуры
Настройте GitHub Actions — уведомления о CI/CD
Email-триггеры — альтернативный способ запуска для систем на электронной почте

Готовы подключить Echobell к своим системам? Создайте первый канал и начните получать мгновенные уведомления.