Webhooks простыми словами: что это и как проектировать аналитику
Rest API — это клиент позвонил на сервер и спросил. А webhook — сервер позвонил клиенту и сказал: «Эй, у нас тут событие».
Когда аналитик проектирует интеграцию, он по умолчанию рисует REST-запросы. Клиент дёргает сервер, получает ответ, всё синхронно. Но половина реальных интеграций работает иначе. Платёжный шлюз сообщает магазину об успешном платеже. CRM оповещает о новой сделке. GitHub дёргает ваш CI при пуше в репозиторий. Ни в одном из этих случаев клиент не опрашивает сервер раз в секунду в надежде на новости.
Это и есть webhook — механизм, при котором источник данных сам отправляет события получателю, когда они происходят.
Как устроен webhook: три шага
Webhook-интеграция состоит из трёх вещей, и аналитик должен зафиксировать каждую в требованиях:
-
Регистрация. Клиент говорит провайдеру: «Я хочу получать события типа
order.paidсюда:https://myshop.ru/hooks/payments». Провайдер возвращаетwebhook_idи, чаще всего, секретный ключ для подписи payload. -
Триггер. Провайдер фиксирует бизнес-событие — платёж прошёл, заказ создан, пользователь зарегистрировался.
-
Доставка. Провайдер делает HTTP POST на зарегистрированный URL. В теле — JSON с данными события, в заголовках — подпись для проверки подлинности. Клиент отвечает
200 OK— доставка засчитана.
На диаграмме видно главное: после регистрации инициатива переходит к провайдеру. Клиент просто ждёт на своём эндпоинте.
Никакого таймера на клиенте. Никаких холостых запросов «есть что-нибудь новенькое?». Это принципиальное отличие от polling, и его стоит запомнить.
Polling vs Webhook: не симметричный выбор
Polling — это когда клиент раз в N секунд спрашивает: «Есть события?» Сервер отвечает: «Нет». И так 99% запросов уходят в пустоту. Или, хуже, «Да, вот 3 события за последние 30 секунд» — и вы получаете их с задержкой до 30 секунд.
Webhook экономит трафик и даёт доставку почти мгновенно (с поправкой на сеть и обработку). Но у него есть цена: клиент должен держать публично доступный эндпоинт, уметь валидировать подпись и корректно обрабатывать дубликаты. Polling проще: он работает даже если сервер клиента за NAT и без белого IP.
Аналитику нужно решить, что выбрать, до передачи требований разработчикам. Вот шпаргалка:
| Критерий | Polling | Webhook |
|---|---|---|
| Реалтайм-доставка | Задержка = интервал опроса | Почти мгновенно |
| Нагрузка на провайдера | Высокая (много холостых запросов) | Низкая (только при событиях) |
| Требования к клиенту | Только исходящие запросы | Должен держать открытый эндпоинт |
| Простота отладки | curl + повторить запрос | Нужна симуляция провайдера |
| Устойчивость к сбоям клиента | Клиент просто перестаёт спрашивать | Провайдер должен ретраить |
Честно говоря, если частота событий больше раза в минуту — webhook почти всегда выигрывает. Если события редкие (раз в час-день), polling с интервалом в 5 минут тоже ок.
Что аналитик должен указать в требованиях к webhook-интеграции
Когда я описываю webhook-интеграцию в ТЗ, я всегда прохожусь по одному и тому же списку. Пропустите любой пункт — разработчики спросят на груминге, и ответа у вас не будет.
События
Какие события провайдер будет отправлять? Не «все подряд», а выверенный список. Для платёжного шлюза: payment.succeeded, payment.failed, refund.processed. Для CRM: lead.created, lead.updated, deal.closed_won.
По каждому событию — описание условия срабатывания. payment.succeeded — когда банк подтвердил списание, не раньше. Не «когда пользователь нажал “Оплатить”», потому что нажатие и списание — разные события с паузой в несколько секунд.
Payload
Структура JSON-тела для каждого события. Минимальный набор:
\{ "event_id": "evt_abc123", "event_type": "payment.succeeded", "timestamp": "2026-11-20T14:30:00Z", "data": \{ "payment_id": "pay_xyz", "amount": 1500.00, "currency": "RUB" \}\}event_id — уникальный идентификатор. Клиент будет использовать его для идемпотентности (чтобы дважды не обработать одно событие при ретраях). timestamp — когда событие произошло на стороне провайдера, а не когда доставлено. Это важно для восстановления хронологии, если события пришли не по порядку.
Безопасность
Три вещи, без которых webhook не должен идти в прод:
- HMAC-подпись. Провайдер подписывает тело запроса секретным ключом, который выдал при регистрации. Заголовок:
X-Signature: sha256=abc.... Клиент пересчитывает подпись на своей стороне и сравнивает. Не совпало — выбрасываем запрос. - HTTPS. Только HTTPS для callback URL. HTTP — только для локальной разработки, и то лучше не привыкать.
- IP-whitelist (опционально). Провайдер публикует список своих IP — клиент принимает запросы только с них. Хорошее дополнение к подписи, но не замена.
Retry-политика
Клиент не всегда доступен. Провайдер должен иметь стратегию повторной доставки. Типичный сценарий: exponential backoff — первая попытка сразу, вторая через минуту, третья через 5, четвёртая через 25. После N неудачных попыток событие помечается как dead и уходит в ручной разбор (или в dead letter queue, если инфраструктура позволяет).
Аналитик должен зафиксировать:
- Сколько попыток доставки
- Интервалы между ними
- Что происходит после исчерпания всех попыток
Без этого разработчики обеих сторон придумают каждый своё — и на проде случится сюрприз.
Продолжение этой темы — событийная архитектура, где webhook становится одним из кирпичиков системы событий. И ещё: если вы проектируете публичный API с webhook-ами для внешних клиентов, пройдитесь по базовым принципам REST API — webhook-эндпоинт на стороне клиента тоже должен им соответствовать.
Идемпотентность
Ретраи неизбежны. Провайдер отправил событие, клиент его обработал, но ответ 200 OK потерялся по пути — провайдер отправит повторно. Клиент получит одно и то же событие дважды.
Единственная защита — проверка event_id на стороне клиента: «я уже обрабатывал событие с таким ID — пропускаю». Это и есть идемпотентность приёма. Как она реализована — забота разработчиков, но аналитик должен явно написать в требованиях: «Клиент обязан обеспечивать идемпотентность обработки входящих webhook-событий по полю event_id».
Порядок доставки
Webhook не гарантирует порядок. Событие order.updated может прийти раньше order.created — если сеть задержала первый запрос и пропустила второй. Аналитик должен решить, критично ли это для бизнес-логики.
Если порядок важен — клиент должен выстроить события по timestamp. А ещё лучше — не закладываться на порядок вообще. Проектировать обработчик так, чтобы он мог принять updated до created: создать сущность по данным из updated, а позже дополнить из created. Это сложнее, но надёжнее. В реальном мире событие «создан» не обязано приходить первым, и не надо ломать систему, пытаясь это гарантировать.
Чек-лист для аналитика
- Определён список событий с условиями срабатывания
- Описана структура payload для каждого события (включая
event_idиtimestamp) - Требование: провайдер подписывает payload (HMAC, минимум SHA-256)
- Требование: callback URL только по HTTPS
- Зафиксирована retry-политика (количество попыток, интервалы, что после исчерпания)
- Требование: клиент обеспечивает идемпотентность по
event_id - Оговорка о порядке доставки (не гарантирован, и как клиенту с этим жить)
- Сценарий отказа: клиент недоступен → ретраи; провайдер недоступен → клиент теряет события? Если да, оговорено.