Webhook простыми словами: как связать событие с действием

Что происходит при Webhook

Представьте, что в Ontik пришла заявка. Команда получила уведомление, но заявку также нужно записать в CRM. Webhook позволяет Ontik сообщить вашей программе: «Появилось новое событие, вот его данные».

Сообщение — обычный HTTP POST на адрес, который вы указали в проекте. На этом адресе находится обработчик: ваша программа, которая принимает JSON и решает, что сделать дальше.

Кто кому отправляет запрос

В текущем Ontik Webhook — исходящий канал: Ontik вызывает URL пользователя. Чтобы отправить инцидент из мониторинга в Ontik, используйте входящий REST API с заголовком X-Ontik-Key.

Некоторые внешние системы называют свои HTTP-скрипты «webhook». Название в интерфейсе источника может отличаться; важно, кто делает запрос и какой JSON принимает другая сторона. Если форматы не совпадают, нужен адаптер.

Пример: заявка превращается в задачу

1. На сайте отправлена форма с номером обращения.
2. Ontik создаёт событие и ставит Web Push в очередь.
3. Отдельная задача отправляет payload на ваш URL.
4. Ваш обработчик проверяет подпись и извлекает request_id.
5. Обработчик создаёт задачу в CRM или сохраняет её для фоновой обработки.

{
  "event_id": "a730caf5-2c37-4191-a232-7b2a12789869",
  "event": "Запрос консультации",
  "meta": {"request_id": "REQ-1048", "service": "Консультация"},
  "created_at": "2026-10-22T00:00:00+00:00"
}

В Ontik нет универсального встроенного коннектора ко всем CRM. Сопоставление полей и вызов API CRM выполняет ваш обработчик. Webhook создаётся для новых событий; изменение статуса само по себе не отправляет отдельный Webhook в текущей реализации.

Зачем нужен длинный секрет

При создании Webhook Ontik показывает секрет whsec_…. Сохраните его сразу: повторно он не отображается. Этот секрет используется для HMAC-SHA256-подписи тела запроса в заголовке X-Ontik-Signature.

Обработчик вычисляет подпись по исходным байтам тела и сравнивает с полученной. Проверка после повторной сериализации JSON может дать другой результат. Секрет Webhook и публичный ключ приёма событий — разные значения с разными задачами.

HTTPS защищает соединение, а подпись помогает проверить отправителя и целостность тела. Подписанный запрос всё ещё может быть повторён, поэтому для защиты от повторной бизнес-операции нужен учёт event_id.

Что будет, если система временно недоступна

Если соединение не удалось или обработчик вернул ошибку, текущий worker повторяет доставку с увеличением задержки, до 8 попыток. Тайм-аут одной отправки — 15 секунд. Возможны повторные запросы с тем же event_id.

Сначала сохраните событие или задачу в своей БД с уникальным ограничением на event_id, затем подтвердите приём ответом 2xx. Для длительных действий используйте свою очередь. Возврат 200 без сохранения задачи может привести к потере обработки при последующем сбое.

Уникальная запись сама по себе не решает все сбои вызова внешней CRM: по возможности используйте её механизм идемпотентности или сопоставление по request_id.

Как попробовать

Сейчас можно посмотреть имитацию события в демо и запустить обработчик локально из документации. Публичная доставка потребует доступного HTTPS endpoint; localhost не доступен серверу Ontik.

В инструкции Webhook есть два полных обработчика на Python и Node.js, проверка подписи и локальный тест без подключения к Ontik. Локальный тест подтверждает работу обработчика, но не заменяет проверку реального пути доставки после настройки проекта.