Webhook

Webhook (вебхук, «веб-крючок») — это механизм, позволяющий внешним сервисам отправлять уведомления вашему боту в реальном времени.

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

Как это работает

Внешний сервис (платёжная система, CRM, хостинг)
│
│ 1. Происходит событие (новый платёж, заказ, регистрация)
↓
[HTTP-запрос]
│
│ 2. Сервис отправляет POST-запрос на URL вашего вебхука
↓
Ваш бот (EnotPro)
│
│ 3. Бот получает данные и выполняет цепочку триггеров
↓
┌────────────────────┐
│ Триггер MAIN       │ ← обработка данных, валидация
└────────────────────┘
↓ (вызов SendResponse)
┌────────────────────┐
│ Триггер START      │ ← подготовка данных для ответа
└────────────────────┘
↓
┌────────────────────┐
│ Отправка ответа    │
└────────────────────┘

Чем вебхук отличается от HTTP-запроса

Зачем нужен вебхук

1. Приём платежей — платёжная система уведомляет бота об успешной оплате.
2. Интеграция с CRM — при изменении статуса заказа CRM присылает обновление.
3. WebApp — ваше веб-приложение может отправлять события боту.
4. Автоматизация — любой внешний сервис, поддерживающий вебхуки, может общаться с вашим ботом.

Как создать вебхук

Шаг 1: Создайте вебхук в интерфейсе EnotPro

1. Перейдите в раздел /adm → Web → Webhook.
2. Нажмите кнопку «Добавить».
3. Дайте вебхуку техническое название (например, yookassa_payments).

Важно: URL вебхука генерируется автоматически. Выглядит он примерно так:

https://enotpro.app/wh/xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx

Вам не нужно придумывать URL — платформа создаёт его сама. Этот URL нужно будет указать во внешнем сервисе.

Шаг 2: Настройте разрешённые методы

Укажите, какие HTTP-методы будет принимать ваш вебхук. Для 99% случаев достаточно POST.

Важно: Если не указать разрешённые методы, вебхук может не принять запрос от сервиса. По умолчанию разрешён только POST.

Шаг 3: Настройте триггеры

У вебхука есть два встроенных триггера (подробнее — в разделе «Триггеры вебхука»). В них вы будете обрабатывать данные, которые прислал внешний сервис.

Шаг 4: Настройте ответ (опционально)

По умолчанию EnotPro отвечает на вебхук кодом 200 OK с пустым телом. Если внешний сервис требует специфический ответ, используйте раздел HTTP-ответы (подробнее — в разделе «Кастомный ответ»).

Шаг 5: Укажите URL вебхука во внешнем сервисе

Скопируйте сгенерированный URL вебхука и вставьте его в настройки внешнего сервиса (платёжной системы, CRM и т.д.).

Шаг 6: Включите вебхук

Переключатель «Включен» должен быть в положении ✅.

Структура входящего запроса

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

Доступные переменные

Как получить данные из тела запроса (JSON)

Если внешний сервис прислал JSON вида:

{
"payment_id": 12345,
"amount": 1000,
"currency": "RUB",
"status": "paid"
}

То доступ к полям:

${web.body.payment_id} → 12345 ${web.body.amount} → 1000 ${web.body.currency} → "RUB" ${web.body.status} → "paid"

Настройки вебхука

Включение/выключение

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

Secret Token (верификация)

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

Как настроить:

1. При создании вебхука укажите Secret Token (любая строка, например my_secret_key_123).
2. В настройках внешнего сервиса укажите этот же токен.
3. В триггере «Подготовка» вебхука проверьте заголовок с токеном.

Рекомендация: Всегда используйте Secret Token для публичных вебхуков, чтобы злоумышленники не могли отправлять ложные запросы.

Ограничения

Что будет при превышении таймаута

Если ваш триггер не успел обработать запрос за 30 секунд:

• ❌ Внешний сервис получит ошибку 504 Gateway Timeout.
• ❌ Скорее всего, сервис повторит отправку вебхука.
• ❌ Вы рискуете получить дублирующуюся обработку.

Как избежать: Выносите длительные операции (отправка сообщений 1000 пользователям, сложные вычисления) в Отложенные действия. В триггере вебхука только сохраняйте данные и запускайте отложенное действие.

Триггеры вебхука

У вебхука есть три встроенных триггера, которые срабатывают в строгой последовательности.

Кастомный ответ

По умолчанию, после выполнения триггера вебхука EnotPro автоматически отправляет ответ с кодом 200 OK и пустым телом. Этого достаточно для большинства сервисов.

Однако некоторые внешние сервисы требуют специфический ответ:

• Определённый JSON (например, {"status": "success"})
• Конкретный HTTP-код (например, 202 Accepted для асинхронной обработки)
• Специальные заголовки

Как настроить кастомный ответ:

1. Перейдите в раздел HTTP-ответы.
2. Создайте новый HTTP-ответ с нужным кодом, заголовками и телом.
3. В триггере вебхука (в «Подготовке» или «Основном») добавьте реакцию SendResponse.
4. Укажите ID созданного HTTP-ответа.

Важно: Если вы отправили кастомный ответ через SendResponse, стандартный ответ 200 OK отправлен не будет.

Пример реализации приема платежей в yookassa

Документация по подключению YouuKassa