Webhook

Что такое webhook

Webhook (вебхук) — способ получать события от чужого сервиса: вы один раз сообщаете ему URL, и при каждом событии сервис сам шлёт на этот адрес HTTP-запрос с данными. Никакого опроса — сервис вызывает вас первым.

Отсюда неформальное название «обратный API». В обычном API инициатор вы: спрашиваете — получаете ответ. В webhook инициатор — сервис: он вызывает ваш эндпоинт, а вы принимаете. Разница ровно в том, кто кому звонит.

Аналогия: polling — это звонить в магазин каждые пять минут и спрашивать, пришёл ли заказ. Webhook — оставить свой номер и дождаться, пока позвонят сами.

Webhook или polling

Polling проще и работает за NAT. Webhook экономнее и быстрее, но требует, чтобы ваш сервер был доступен извне и держал нагрузку в момент всплеска событий.

Как выглядит вызов

Сервис делает обычный POST с JSON-телом:

POST /hooks/payments HTTP/1.1
Host: app.example.com
Content-Type: application/json
X-Signature: sha256=6f1a...c9
X-Event-Id: evt_01HQ8

{
  "event": "payment.succeeded",
  "created_at": "2026-01-17T09:14:02Z",
  "data": { "order_id": "A-1042", "amount": 4990, "currency": "RUB" }
}

От вас требуется ответить кодом 2xx — это подтверждение приёма. Любой другой код ответа или таймаут источник считает неудачей и повторит доставку.

Правила приёмника

• Проверяйте подпись. URL вебхука рано или поздно утечёт, и на него начнут слать что попало. Источник подписывает тело секретом (обычно HMAC-SHA256), а вы пересчитываете подпись и сравниваете. Без проверки любой желающий «оплатит» заказ.
• Отвечайте сразу. Приняли, положили в очередь через брокер сообщений, ответили 200. Если обрабатывать синхронно, источник поймает таймаут и пришлёт дубль.
• Будьте идемпотентны. Ретраи неизбежны, поэтому одно и то же событие придёт дважды. Храните event_id обработанных событий и игнорируйте повторы, иначе клиент получит два письма, а склад — два списания.
• Не доверяйте телу запроса. Сумму и статус перепроверяйте запросом в API источника, а не берите из payload.
• Порядок не гарантирован. События могут прийти не в том порядке, в каком произошли, — ориентируйтесь на временные метки.

Проверка подписи на Python:

import hashlib, hmac

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", header)

Считать нужно от сырого тела запроса: пересобранный из объекта JSON даст другие байты и подпись не сойдётся.

Инфраструктура

Эндпоинт вебхука должен быть публичным и работать по HTTPS — Nginx терминирует TLS и проксирует на приложение. Ставить его за VPN нельзя: источник должен достучаться из интернета. Ограничить доступ помогает список IP-адресов источника в firewall, если провайдер их публикует.

Нагрузка неравномерная: рассылка может прийти пачкой в тысячи событий за секунду. Отсюда лёгкий приёмник, очередь и autoscaling воркеров, а не обработка в момент приёма. Отладке помогает лог сырых запросов и HAR-файл с фактическими заголовками.

Связанные термины

• API — вызов в прямом направлении
• API endpoint — адрес, который принимает вебхуки
• Telegram-боты — типичный пример работы через webhook
• Брокеры сообщений — куда складывать события до обработки
• HTTP-ошибки — что означает ответ приёмника
• WebSocket — альтернатива для постоянного двустороннего канала