Logo
Overview

Webhooks простыми словами: что это и как проектировать аналитику

November 20, 2026
6 min read

Webhooks простыми словами: что это и как проектировать аналитику

Rest API — это клиент позвонил на сервер и спросил. А webhook — сервер позвонил клиенту и сказал: «Эй, у нас тут событие».

Когда аналитик проектирует интеграцию, он по умолчанию рисует REST-запросы. Клиент дёргает сервер, получает ответ, всё синхронно. Но половина реальных интеграций работает иначе. Платёжный шлюз сообщает магазину об успешном платеже. CRM оповещает о новой сделке. GitHub дёргает ваш CI при пуше в репозиторий. Ни в одном из этих случаев клиент не опрашивает сервер раз в секунду в надежде на новости.

Это и есть webhook — механизм, при котором источник данных сам отправляет события получателю, когда они происходят.

Как устроен webhook: три шага

Webhook-интеграция состоит из трёх вещей, и аналитик должен зафиксировать каждую в требованиях:

  1. Регистрация. Клиент говорит провайдеру: «Я хочу получать события типа order.paid сюда: https://myshop.ru/hooks/payments». Провайдер возвращает webhook_id и, чаще всего, секретный ключ для подписи payload.

  2. Триггер. Провайдер фиксирует бизнес-событие — платёж прошёл, заказ создан, пользователь зарегистрировался.

  3. Доставка. Провайдер делает HTTP POST на зарегистрированный URL. В теле — JSON с данными события, в заголовках — подпись для проверки подлинности. Клиент отвечает 200 OK — доставка засчитана.

100%
sequenceDiagram
  participant C as Клиент<br/>(Consumer)
  participant P as Провайдер<br/>(Webhook Source)
  participant S as Сервер клиента<br/>(Webhook Receiver)

  Note over C,P: Регистрация webhook
  C->>P: POST /webhooks (URL + события)
  P-->>C: 201 + webhook_id + secret

  Note over P,S: Срабатывание события
  P->>P: Происходит событие
  P->>S: POST https://client.ru/hooks {payload, signature}
  S-->>P: 200 OK

На диаграмме видно главное: после регистрации инициатива переходит к провайдеру. Клиент просто ждёт на своём эндпоинте.

Никакого таймера на клиенте. Никаких холостых запросов «есть что-нибудь новенькое?». Это принципиальное отличие от polling, и его стоит запомнить.

Polling vs Webhook: не симметричный выбор

Polling — это когда клиент раз в N секунд спрашивает: «Есть события?» Сервер отвечает: «Нет». И так 99% запросов уходят в пустоту. Или, хуже, «Да, вот 3 события за последние 30 секунд» — и вы получаете их с задержкой до 30 секунд.

100%
graph TD
  A["Бизнес-событие"] --> B{"Механизм<br/>уведомления"}
  B -->|Polling| C["Клиент периодически<br/>опрашивает сервер"]
  B -->|Webhook| D["Сервер сам отправляет<br/>событие клиенту"]
  C --> E["GET /orders?since=..."]
  E --> F["Лишние запросы,<br/>задержка до polling_interval"]
  D --> G["POST на callback-url<br/>с payload события"]
  G --> H["Мгновенная доставка,<br/>трафик только при событиях"]

  style A fill:#7b68ee,stroke:#5a4db2,color:#fff
  style B fill:#f0a500,stroke:#c88400,color:#fff
  style C fill:#e0e0e0,stroke:#999,color:#333
  style D fill:#50c878,stroke:#3a9a5c,color:#fff
  style E fill:#e0e0e0,stroke:#999,color:#333
  style F fill:#e0e0e0,stroke:#999,color:#333
  style G fill:#50c878,stroke:#3a9a5c,color:#fff
  style H fill:#50c878,stroke:#3a9a5c,color:#fff

Webhook экономит трафик и даёт доставку почти мгновенно (с поправкой на сеть и обработку). Но у него есть цена: клиент должен держать публично доступный эндпоинт, уметь валидировать подпись и корректно обрабатывать дубликаты. Polling проще: он работает даже если сервер клиента за NAT и без белого IP.

Аналитику нужно решить, что выбрать, до передачи требований разработчикам. Вот шпаргалка:

КритерийPollingWebhook
Реалтайм-доставкаЗадержка = интервал опросаПочти мгновенно
Нагрузка на провайдераВысокая (много холостых запросов)Низкая (только при событиях)
Требования к клиентуТолько исходящие запросыДолжен держать открытый эндпоинт
Простота отладки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 не должен идти в прод:

  1. HMAC-подпись. Провайдер подписывает тело запроса секретным ключом, который выдал при регистрации. Заголовок: X-Signature: sha256=abc.... Клиент пересчитывает подпись на своей стороне и сравнивает. Не совпало — выбрасываем запрос.
  2. HTTPS. Только HTTPS для callback URL. HTTP — только для локальной разработки, и то лучше не привыкать.
  3. 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
  • Оговорка о порядке доставки (не гарантирован, и как клиенту с этим жить)
  • Сценарий отказа: клиент недоступен → ретраи; провайдер недоступен → клиент теряет события? Если да, оговорено.