---
title: Интеграция вебхуков - полное руководство по HTTP-триггерам
sidebarTitle: Вебхуки
description: "Интеграция вебхуков Echobell: 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-запрос

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

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

### POST-запрос

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

```http
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`, и уведомление не отправляется:

```json
{
  "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`: если передать её в запросе, в списке записей уведомлений появится кликабельная ссылка. Удобно, чтобы вести к подробностям или связанным ресурсам.

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

```http
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.`. Полный список и примеры см. в разделе [Условия](/docs/conditions).

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

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

### DevOps и мониторинг
- **Мониторинг серверов**: оповещения о загрузке CPU, памяти и диска из систем мониторинга вроде [Prometheus](/docs/developer/prometheus) или [Grafana](/docs/developer/grafana)
- **Мониторинг доступности**: оповещения о доступности сайтов и сервисов из [Uptime Kuma](/docs/developer/uptime-kuma) или [UptimeRobot](/docs/developer/uptimerobot)
- **Мониторинг контейнеров**: сбои Docker, падения подов Kubernetes и нехватка ресурсов
- **Агрегация логов**: критические ошибки и исключения из систем управления логами

### Разработка и CI/CD
- **Уведомления о сборках**: упавшие сборки, результаты тестов, статус развёртывания из [GitHub Actions](/docs/developer/github) или GitLab CI
- **Качество кода**: ошибки линтера, уязвимости, изменения покрытия тестами
- **События репозитория**: пул-реквесты, коммиты, релизы и активность соавторов
- **Отслеживание развёртываний**: успешные деплои, откаты и изменения окружений

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

### IoT и умный дом
- **События умного дома**: датчики дверей, детекция движения, изменения температуры через [Home Assistant](/docs/developer/home-assistant)
- **IoT-устройства**: показания датчиков, изменения статуса устройств, проблемы со связью
- **Системы безопасности**: срабатывания сигнализации, движение в кадре камеры, события контроля доступа
- **Мониторинг среды**: превышение порогов по температуре, влажности и качеству воздуха

### Трейдинг и финансы
- **Рыночные оповещения**: движения цен, технические индикаторы из [TradingView](/docs/trader/tradingview)
- **Мониторинг портфеля**: изменения позиций, маржин-коллы, остатки на счетах
- **Экономические события**: выход новостей, отчёты о прибыли, изменения настроений рынка

Инструкции по настройке для популярных платформ — в наших [руководствах по интеграциям](/docs/features).

## Рекомендации

### Обработка ошибок
Не полагайтесь только на HTTP-статус — всегда разбирайте тело JSON-ответа и проверяйте поле `success`:

- **200 OK**: запрос получен. Проверьте тело JSON: `success: true` означает, что канал был запущен, а `success: false` — что запрос принят, но уведомление не отправлено (например, при неизвестном токене канала, который тоже возвращает HTTP 200).
- **400 Bad Request**: неверная длина токена канала. Исправьте URL вебхука.
- **405 Method Not Allowed**: у канала включена настройка [Только POST](#только-post), а запрос был не `POST`. Переведите вызывающую сторону на `POST` или отключите настройку.
- **500 Server Error**: временная проблема, повторите запрос с экспоненциальной задержкой

Echobell не ограничивает частоту вызовов вебхуков, поэтому ответа `429` не бывает. Поскольку неизвестный (но корректной длины) токен всё равно возвращает `200` с `success: false`, всегда ветвите логику по полю `success` в JSON, а не по HTTP-статусу.

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

- Для непрерывного мониторинга объединяйте несколько событий в одно уведомление
- Используйте [условия](/docs/conditions), чтобы отсеивать некритичные события
- Подумайте об агрегации событий, идущих подряд (например, нескольких ошибок за короткое время)
- Не отправляйте подряд одинаковые триггеры — так критичные оповещения останутся надёжными

### Безопасность данных
Делитесь URL вебхуков только с доверенными системами и сервисами:

- Относитесь к URL вебхуков как к секретам — они дают прямую возможность отправлять уведомления
- Не коммитьте URL вебхуков в публичные репозитории и не публикуйте их в открытой документации
- Периодически меняйте URL вебхуков, а также когда кто-то уходит из команды
- Используйте функцию канала «Сбросить токен», чтобы обесценить старые URL, если они скомпрометированы
- Храните URL в переменных окружения или в системах управления секретами

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

- Давайте описательные имена: `server_name` вместо `s` или `srv`
- Придерживайтесь единого соглашения об именовании во всех каналах
- Документируйте, какие переменные ожидают ваши шаблоны
- Перед отправкой проверяйте, что переданы все обязательные переменные

### Тестирование
Тщательно протестируйте интеграцию с вебхуком, прежде чем запускать её в продакшене:

1. Для первых проверок используйте `curl`, Postman или HTTP-клиент вашего языка
2. Начните с простых шаблонов и постепенно усложняйте их
3. Проверьте оба метода, GET и POST, чтобы понять, какой подходит лучше
4. Убедитесь, что специальные символы и Unicode обрабатываются правильно
5. Проверьте сценарии с ошибками (пропущенные переменные, некорректный JSON), чтобы понимать поведение
6. Во время разработки используйте [тестовые каналы](/docs), отдельные от рабочих

### Проектирование шаблонов
Проектируйте шаблоны так, чтобы они оставались полезными и без необязательных переменных:

- Задавайте значения по умолчанию или запасные варианты для необязательных данных
- Стройте шаблоны так, чтобы они аккуратно переживали отсутствие переменных
- Тестируйте шаблоны с разными сочетаниями присутствующих и отсутствующих переменных
- Для необязательных частей используйте [условные выражения](/docs/template)

### Мониторинг
Следите за своими интеграциями с вебхуками, чтобы убедиться, что они работают правильно:

- Логируйте успешные и неудачные вызовы вебхука в своём приложении
- Отслеживайте долю доставленных уведомлений и время ответа
- Настройте оповещения об ошибках вебхуков и о нетипичном поведении
- Периодически пересматривайте и проверяйте критичные интеграции

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

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

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

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

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

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

### Рекомендации по безопасности

- **Относитесь к URL вебхуков как к API-ключам** — они дают возможность отправлять уведомления без аутентификации
- **Регулярно меняйте URL** — используйте функцию «Сбросить токен», чтобы получить новые
- **Используйте HTTPS-клиенты** — мы принимаем только HTTPS-соединения, но убедитесь, что ваш клиент проверяет сертификаты
- **Проверяйте источники вызовов** — по возможности ограничьте, какие IP-адреса или сервисы могут обращаться к вашим вебхукам
- **Следите за злоупотреблениями** — обращайте внимание на нетипичные всплески и несанкционированное использование
- **Разделяйте окружения** — используйте разные каналы для разработки, тестирования и продакшена

Подробнее — в нашей [документации по поддержке](/docs/support).

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

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

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

1. **Проверьте, что URL вебхука верный**
   - Скопируйте URL прямо из приложения Echobell
   - Убедитесь, что не добавились лишние пробелы или символы
   - Проверьте, что вы используете `https://hook.echobell.one/t/`, а не другой домен

2. **Проверьте, активен ли канал**
   - Откройте канал в приложении Echobell
   - Убедитесь, что он не удалён и не архивирован
   - Проверьте, что вы не сбрасывали токен вебхука (это делает старый URL недействительным)

3. **Убедитесь, что тело JSON оформлено корректно** (для POST-запросов)
   - Проверьте полезную нагрузку валидатором JSON
   - Убедитесь, что строки заключены в кавычки
   - Проверьте, что заголовок Content-Type установлен в `application/json`

4. **Убедитесь, что переданы все переменные, которые нужны вашим шаблонам**
   - Посмотрите в шаблонах уведомлений, какие переменные они используют
   - Проверьте, что эти переменные есть в запросе к вебхуку (в параметрах строки запроса или в теле JSON)
   - Помните: отсутствующие переменные подставляются как пустые строки

5. **Проверьте, есть ли у канала активные подписчики**
   - Уведомления отправляются, только если кто-то подписан на канал
   - Проверьте свою подписку в списке каналов в приложении
   - Убедитесь, что подписки не были случайно удалены

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

1. **Имена переменных не совпадают**
   - В шаблоне используется `{{server_name}}`, а вебхук отправляет `serverName`
   - Имена переменных чувствительны к регистру и должны совпадать точно
   - Проверьте, нет ли опечаток в именах переменных

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

3. **Проблемы из-за специальных символов**
   - Корректно кодируйте параметры строки запроса
   - Экранируйте специальные символы JSON в телах POST-запросов
   - Сначала проверьте на простом ASCII-тексте

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

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

```bash
# 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"}'
```

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

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

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

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

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

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

- **[Изучите синтаксис шаблонов](/docs/template)** — создавайте динамичные и информативные уведомления
- **[Используйте условия](/docs/conditions)** — фильтруйте уведомления по данным
- **[Изучите интеграции](/docs/features)** — подключайтесь к инструментам, которыми вы уже пользуетесь
- **[Настройте оповещения Grafana](/docs/developer/grafana)** — мониторинг инфраструктуры
- **[Настройте GitHub Actions](/docs/developer/github)** — уведомления о CI/CD
- **[Email-триггеры](/docs/email-trigger)** — альтернативный способ запуска для систем на электронной почте

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