Webhook: определение и принцип работы¶
Webhook — это механизм автоматического уведомления одного приложения о событии, произошедшем в другом, посредством HTTP-запроса, отправляемого по заранее заданному URL-адресу. В отличие от опроса (polling), при котором клиент периодически запрашивает сервер о наличии новых данных, webhook работает по модели push: сервер сам инициирует запрос к внешнему сервису, как только происходит значимое событие. Термин ввёл Джефф Линднер (Jeff Lindsay) в 2009 году как «webhook» — «web» плюс «hook» (крючок), подразумевая подключение к веб-событиям.
¶Принцип работы
Базовый сценарий взаимодействия выглядит следующим образом:
- Клиентское приложение регистрирует у сервиса URL-адрес (эндпоинт), на который будут приходить уведомления.
- Сервис сохраняет этот адрес и связывает его с конкретными событиями (например, «создан новый заказ», «получено сообщение»).
- При наступлении события сервис формирует HTTP-запрос (обычно POST) с данными о событии в теле запроса и отправляет его на зарегистрированный URL.
- Приёмник (webhook-эндпоинт) обрабатывает полученные данные и возвращает ответ, как правило, HTTP 200 OK, подтверждая приём.
Тело запроса чаще всего содержит данные в формате JSON или XML. Ключевые элементы запроса:
| Элемент | Назначение |
|---|---|
| URL-эндпоинт | Адрес приёмника уведомлений |
| HTTP-метод | Обычно POST |
| Тело запроса | JSON/XML с данными о событии |
| Заголовки | Метаданные, включая подпись |
| Событие (event) | Тип произошедшего события |
¶Схема подписи и безопасность
Поскольку webhook-эндпоинт — это публично доступный HTTP-адрес, его могут вызвать и злоумышленники. Для защиты от подделки запросов сервисы используют цифровые подписи. Наиболее распространённый подход — HMAC (Hash-based Message Authentication Code): сервис вычисляет хеш от тела запроса с использованием секретного ключа и добавляет его в заголовок (например, X-Hub-Signature-256 у GitHub). Приёмник повторно вычисляет хеш и сверяет его с полученным значением. Если подписи не совпадают, запрос отклоняется.
Другие меры безопасности:
- Использование HTTPS для шифрования трафика.
- Проверка IP-адресов отправителя по опубликованным спискам.
- Ограничение времени жизни запроса (timeout) для защиты от атак типа slowloris.
- Верификация токенов в заголовках.
¶Надёжность доставки
HTTP не гарантирует доставку запроса: соединение может оборваться, приёмник может быть недоступен. Поэтому зрелые webhook-сервисы реализуют механизмы повторной отправки (retry). Обычная практика:
- Приёмник в течение короткого времени (например, 5–10 секунд) должен вернуть 2xx-ответ, иначе сервис считает доставку неудачной.
- При неудаче запрос повторяется с экспоненциальной задержкой (например, через 1, 5, 25, 125 минут).
- Сервисы вроде GitHub, Stripe и Twilio ведут журнал доставок, позволяя вручную повторить неудавшийся вызов.
Некоторые сервисы (например, Shopify) поддерживают ретраи с настраиваемой политикой, а также предоставляют веб-интерфейс для просмотра истории запросов и их повторного проигрывания.
¶Сравнение с polling
| Критерий | Webhook | Polling |
|---|---|---|
| Инициатор запроса | Сервер-источник | Клиент |
| Задержка | Минимальная (сразу после события) | Зависит от интервала опроса |
| Нагрузка на сеть | Низкая (запросы только по событиям) | Постоянная, независимо от событий |
| Сложность реализации | Требует публичного эндпоинта и обработки ошибок | Проще, но менее эффективно |
| Примеры | GitHub, Stripe, Slack | Старые RSS-ридеры, мониторинг статуса |
¶Типичные сценарии применения
Webhook широко используется в интеграциях между SaaS-сервисами и внутренними системами:
- Платёжные системы: Stripe, ЮKassa и PayPal отправляют уведомления о статусе платежа (успешном, отменённом, возвратном).
- CI/CD: GitLab, GitHub Actions и Jenkins вызывают внешние пайплайны по событию push или pull request.
- Мессенджеры и CRM: Slack, Telegram Bot API и amoCRM уведомляют о новых сообщениях и заявках.
- Мониторинг: Sentry, UptimeRobot и Prometheus Alertmanager дёргают вебхуки при инцидентах.
- Платформы e-commerce: Shopify и WooCommerce уведомляют о новых заказах для синхронизации складского учёта.
¶Ограничения
Webhook не лишен недостатков. Приёмник должен быть доступен из интернета, что не всегда возможно во внутренней сети без использования туннелей (ngrok, Cloudflare Tunnel) или шлюзов. Порядок доставки не гарантирован: два события могут прийти не в том порядке, в котором они произошли, поэтому приёмнику часто требуется идемпотентность — способность обрабатывать повторно доставленные события без побочных эффектов. Наконец, отладка webhook-интеграций сложнее, чем polling, из-за асинхронного характера и возможных повторных попыток.
Источники:
- Документация GitHub Webhooks
- Документация Stripe Webhooks
- Документация Slack Events API
- RFC 6749 (OAuth 2.0) и рекомендации по подписи запросов
- Jeff Lindsay, «Webhooks» (webhooks.org), 2009