Вебхук — механизм автоматического уведомления¶
Вебхук (webhook) — механизм передачи данных между веб-сервисами, при котором одна система автоматически отправляет другой системе HTTP-запрос (обычно POST) при наступлении определённого события. В отличие от классического API-запроса, инициируемого клиентом, вебхук инициирует отправку данных «сам» источник события, что делает его основой асинхронного взаимодействия между сервисами.
¶Принцип работы
Вебхук реализует модель «уведомление по подписке». Одна система (потребитель) регистрирует у источника события (поставщика) URL-адрес — так называемый «эндпоинт вебхука». Когда в системе-источнике происходит заранее оговорённое событие (оплата, регистрация пользователя, изменение файла, получение письма и т. д.), источник формирует HTTP-запрос и отправляет его на зарегистрированный URL. Тело запроса обычно содержит данные о событии в формате JSON или XML.
Ключевое отличие вебхука от обычного API-опроса (polling) состоит в том, что потребитель не обязан периодически опрашивать источник, чтобы узнать о новых данных. Источник сам «доставляет» данные по мере их появления, что снижает задержку и нагрузку на обе стороны.
¶Типовой сценарий взаимодействия
- Клиентская система запрашивает у источника регистрацию вебхука, передавая URL приёмника и тип интересующих событий.
- Источник подтверждает регистрацию (часто отправкой тестового запроса).
- При наступлении события источник формирует HTTP POST-запрос с полезной нагрузкой и отправляет его на URL приёмника.
- Приёмник обрабатывает запрос и возвращает HTTP-ответ (обычно 200 OK) в течение ограниченного времени — как правило, нескольких секунд.
- Если источник не получает подтверждение или получает ошибку, он может повторить отправку с интервалом (retry) в течение некоторого времени.
¶Виды вебхуков
| Тип | Описание |
|---|---|
| Исходящие (outgoing) | Сервис сам отправляет уведомления на внешний URL при событии |
| Входящие (incoming) | Сервис принимает внешние HTTP-запросы по заранее определённому формату |
| Подписанные (signed) | Каждый запрос снабжается криптографической подписью (HMAC) для проверки подлинности |
| С фильтрацией | Источник отправляет только события, выбранные потребителем по типу или параметрам |
¶Вопросы безопасности
Поскольку вебхук представляет собой открытый HTTP-эндпоинт, принимающий данные извне, его защита — важная задача. Основные методы:
- Проверка подписи. Источник вычисляет HMAC-подпись от тела запроса с использованием общего секрета и передаёт её в заголовке. Приёмник пересчитывает подпись и отклоняет запрос при несовпадении.
- Секретные токены. URL вебхука может содержать случайный токен, известный обеим сторонам.
- Ограничение источников. Приёмник проверяет IP-адрес отправителя по опубликованному списку подсетей источника.
- Проверка временной метки. Запросы с устаревшим временем генерации отклоняются, что снижает риск повторной атаки (replay attack).
- HTTPS. Все вебхуки передаются по защищённому каналу.
¶Применение
Вебхуки широко используются в интеграциях SaaS-сервисов и платёжных систем. Платёжные шлюзы (ЮKassa, Stripe, PayPal) уведомляют магазины о статусе платежа. Системы контроля версий (GitHub, GitLab) сообщают о push-коммитах и pull request'ах. CRM-системы, сервисы рассылок, мессенджеры (Telegram Bot API, Slack, Discord) используют вебхуки для передачи событий и сообщений. В России вебхуки применяются в интеграциях с 1С, amoCRM, Битрикс24, а также в государственных системах электронного документооборота.
¶Преимущества и ограничения
Преимущества: низкая задержка доставки, отсутствие накладных расходов на опрос, масштабируемость (источник не хранит очередь запросов), простота реализации.
Ограничения: зависимость от доступности приёмника (при недоступности URL источник вынужден повторять отправку), сложность отладки асинхронного взаимодействия, необходимость тщательной проверки подлинности входящих запросов, риск потери событий при сбоях без механизма повторов.
¶История
Термин «webhook» ввёл Джефф Линдси (Jeff Lindsay) в 2007 году в блоге ProgrammableWeb, предложив его как «пользовательские HTTP-колбэки». Идея получила распространение вместе с развитием RESTful API и облачных сервисов в конце 2000-х — начале 2010-х годов.
¶Источники
- Линдси Д. Web Hooks: «Just-in-Time AJAX» // ProgrammableWeb, 2007
- Fielding R. T. Architectural Styles and the Design of Network-based Software Architectures (диссертация, 2000)
- Документация платформ: GitHub Webhooks API, Telegram Bot API, Stripe Webhooks