Вебхук — механизм автоматической передачи данных¶
Вебхук (webhook) — это механизм автоматического уведомления одного приложения о событии, произошедшем в другом, посредством HTTP-запроса, отправляемого на заранее заданный URL-адрес. В отличие от классического подхода, когда клиент периодически опрашивает сервер на наличие обновлений (поллинг), вебхук реализует модель «push»: событие инициирует отправку данных, и получатель не тратит ресурсы на постоянные проверки.
¶Принцип работы
Вебхук функционирует по схеме «подписка — уведомление»:
- Регистрация. Получатель данных (subscriber) указывает у провайдера события URL-адрес (callback URL), на который должны приходить уведомления. Часто подписка сопровождается выбором типа событий (например, «платёж завершён», «заказ создан»).
- Событие. Источник данных (провайдер) фиксирует событие — например, пользователь оплатил товар.
- Отправка. Провайдер формирует HTTP-запрос (обычно POST) с полезной нагрузкой (payload), чаще всего в формате JSON, и направляет его на зарегистрированный URL.
- Обработка. Получатель принимает запрос, проверяет его подлинность (см. раздел «Безопасность»), разбирает данные и выполняет нужные действия: обновляет базу данных, отправляет письмо, запускает бизнес-процесс.
¶Отличие от поллинга
| Критерий | Поллинг | Вебхук |
|---|---|---|
| Инициатор запроса | Клиент | Сервер-источник |
| Частота запросов | Периодическая, постоянная | Только при наступлении события |
| Задержка данных | До интервала опроса | Секунды |
| Нагрузка на сервер | Высокая при большом числе клиентов | Минимальная |
| Сложность реализации | Простая | Требует публичного URL и обработки ошибок |
¶Формат и протокол
Вебхуки используют стандартный HTTP/HTTPS. Наиболее распространён метод POST с телом в формате JSON. Некоторые провайдеры поддерживают альтернативные форматы — XML, form-encoded. В заголовке запроса могут передаваться метаданные: идентификатор события, его тип, время отправки, подпись.
¶Безопасность
Поскольку URL вебхука — это открытый HTTP-эндпоинт, его защита критически важна:
- Проверка подписи. Провайдер подписывает тело запроса секретным ключом (например, HMAC-SHA256) и передаёт подпись в заголовке. Получатель пересчитывает подпись и сверяет её, отклоняя запрос при несовпадении.
- Секретный токен. В URL или заголовке может передаваться случайный токен, известный обеим сторонам.
- HTTPS. Обязательное шифрование канала передачи для защиты данных от перехвата.
- Проверка источника. Сверка IP-адреса отправителя с публикуемым списком адресов провайдера.
- Идемпотентность. Обработка должна учитывать, что провайдер может повторно отправить уведомление при таймауте — дубликаты нужно распознавать по идентификатору события.
¶Надёжность доставки
HTTP-запрос не гарантирует доставку: получатель может быть недоступен, сеть — кратковременно прерваться. Для повышения надёжности провайдеры применяют:
- повторные попытки отправки с нарастающей задержкой (retry с exponential backoff);
- очередь сообщений и буферизацию;
- подтверждение обработки (acknowledgement) — получатель возвращает код 2xx, иначе провайдер повторяет отправку;
- вебхуки-«ретраеры» — промежуточные сервисы (например, ngrok, Hookdeck), гарантирующие доставку.
¶Применение
Вебхуки широко используются в интеграции SaaS-сервисов и платёжных систем:
- Платежи. Stripe, ЮKassa, PayPal уведомляют магазин о статусе транзакции.
- Контроль версий. GitHub, GitLab отправляют уведомления о пуше, открытии pull request, выпуске релиза.
- Мессенджеры и CRM. Telegram Bot API, Slack, AmoCRM, Битрикс24 используют вебхуки для передачи событий о сообщениях, заявках, изменениях сделок.
- CI/CD. Jenkins, GitLab CI запускают сборку по вебхуку от репозитория.
- Уведомления. Сервисы мониторинга (UptimeRobot, PagerDuty) оповещают о сбоях.
¶История термина
Термин «webhook» закрепился в середине 2000-х годов в связи с проектом GitHub и обсуждениями в блогах Джеффа Линдсея (Jeff Lindsay) и других разработчиков. Идея «обратного вызова по HTTP» существовала и раньше — например, XML-RPC и SOAP-колбэки, — но именно вебхуки сделали её массовой за счёт простоты: обычный HTTP POST вместо сложных RPC-протоколов.
¶Ограничения
Вебхуки не лишены недостатков: получателю необходим публично доступный URL, что усложняет локальную разработку; отсутствие гарантии доставки требует реализации повторов; при высокой нагрузке нужна очередь обработки. Для сценариев, где важна актуальность данных без задержек и события носят регулярный характер, вебхук остаётся наиболее экономичным решением по сравнению с поллингом.
Источники:
- Fielding, R. T. Architectural Styles and the Design of Network-based Software Architectures. — University of California, Irvine, 2000.
- Richardson, L., Amundsen, M., Ruby, S. RESTful Web APIs. — O'Reilly Media, 2013.
- Mozilla Developer Network: Webhooks — концепции и практики.
- Stripe Documentation: Webhooks.
- GitHub Docs: Webhooks.