Веб-хук¶

Веб-хук (англ. webhook, от web — «сеть» и hook — «крючок») — это механизм автоматической передачи данных между информационными системами, при котором одна система (источник) отправляет HTTP-запрос (обычно POST) на заранее заданный URL-адрес другой системы (получателя) при наступлении определённого события. В отличие от традиционного опроса (polling), веб-хуки работают по принципу «push»: данные отправляются немедленно после события, без необходимости постоянных запросов со стороны получателя.

¶Принцип работы

Веб-хук реализуется на основе клиент-серверной архитектуры поверх протокола HTTP/HTTPS. Процесс включает три ключевых этапа:

Регистрация URL. Получатель (приложение, сервис) предоставляет источнику событий уникальный URL-адрес (endpoint), на который будут отправляться уведомления. Обычно это делается через настройки API или панель управления.

Наступление события. В системе-источнике происходит определённое событие (например, новый заказ, изменение статуса, загрузка файла). Источник формирует HTTP-запрос, содержащий полезную нагрузку (payload) — данные о событии в структурированном формате (чаще всего JSON или XML).

Отправка запроса. Источник отправляет POST-запрос на зарегистрированный URL. Получатель обрабатывает запрос, извлекает данные и выполняет соответствующее действие (например, обновляет базу данных, отправляет уведомление, запускает бизнес-процесс).

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

¶Отличие от других методов интеграции

¶Веб-хук и API-запросы (polling)

При использовании традиционного REST API получатель периодически (например, каждые 5 минут) отправляет запросы к источнику, чтобы проверить наличие новых данных. Веб-хук устраняет необходимость в таких постоянных опросах: данные доставляются только при реальном изменении, что снижает нагрузку на серверы и уменьшает задержки.

¶Веб-хук и WebSocket

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

¶Форматы данных и безопасность

¶Полезная нагрузка

Данные в веб-хуках передаются в теле HTTP-запроса. Наиболее распространённые форматы:

JSON — стандартный формат для большинства современных API (например, GitHub, Stripe, Slack).
XML — используется в некоторых корпоративных системах (например, Salesforce).
application/x-www-form-urlencoded — встречается в старых интеграциях.

¶Аутентификация и верификация

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

Секретный токен (secret) — источник включает в заголовок запроса (например, X-Hub-Signature) подпись, вычисленную на основе тела запроса и общего секретного ключа. Получатель проверяет подпись, чтобы убедиться, что запрос не был подменён.
IP-белые списки — получатель принимает запросы только с известных IP-адресов источника.
HTTPS — обязательное использование шифрования для защиты данных при передаче.

¶Примеры использования

¶Системы контроля версий

GitHub, GitLab и Bitbucket отправляют веб-хуки при наступлении событий: push коммитов, создание pull request, открытие issue. Получатель (например, CI/CD-сервер Jenkins) может автоматически запускать сборку, тестирование или развёртывание.

¶Платёжные системы

Stripe, PayPal, Яндекс.Касса (входит в группу Сбера) уведомляют о статусе транзакций: успешный платёж, возврат, отклонение. Это позволяет интернет-магазинам мгновенно обновлять статус заказа без периодических запросов к API.

¶Мониторинг и оповещения

Сервисы мониторинга (PagerDuty, Opsgenie, Zabbix) отправляют веб-хуки в мессенджеры (Slack, Telegram) или системы управления инцидентами при превышении пороговых значений метрик.

¶Интернет вещей (IoT)

Устройства (датчики температуры, умные замки) отправляют веб-хуки на облачные серверы при изменении состояния, что позволяет реализовать сценарии автоматизации (например, включение кондиционера при повышении температуры).

¶Реализация веб-хуков

¶Для отправителя

Разработчик должен:

Определить список событий, по которым будут отправляться уведомления.
Реализовать HTTP-клиент, формирующий POST-запрос с данными события.
Предоставить интерфейс для регистрации URL получателя (обычно через REST API или графический интерфейс).
Реализовать механизм повторных отправок и логирования ошибок.

¶Для получателя