Webhook

Определение

Webhook (вебхук, «обратный вызов») — это механизм, при котором одна система автоматически отправляет HTTP-запрос (обычно POST) на заранее заданный URL другой системы в момент наступления определённого события. В отличие от классического API-запроса, где клиент сам «спрашивает» сервер о данных, здесь инициатором выступает сервер-источник: он «стучится» к вам сам, как только что-то произошло.

Простыми словами: вы не звоните в службу доставки каждые 5 минут с вопросом «где посылка?», а оставляете номер телефона — и курьер сам сообщает, когда заказ передан, отгружен или доставлен.

Для DTC-бренда вебхук — это фундамент real-time синхронизации между магазином, складом (WMS), службой доставки, платёжным шлюзом и CRM. Без вебхуков вы либо работаете на устаревших данных, либо вынуждены постоянно опрашивать (polling) чужие серверы, что бьёт по лимитам и по кошельку.

Аналогия из жизни

Представьте пункт выдачи заказов. Есть два способа узнать о приходе вашей посылки:

1. Polling — вы каждый день звоните на склад и спрашиваете: «Моя посылка уже пришла? А сегодня? А сейчас?» 30 звонков в месяц — и всё равно узнаёте с задержкой.

2. Webhook — вы оставляете номер телефона и подписываетесь на SMS. Как только коробка сканируется на складе, вам приходит уведомление. Один раз настроили — и получаете события мгновенно.

Вебхук — это та самая SMS-подписка, только вместо телефона — URL-эндпоинт (https://api.myshop.ru/hooks/orders), а вместо SMS — JSON-payload.

Формула и техническая механика

Упрощённая модель срабатывания:

Событие → Триггер → HTTP POST → URL получателя → 200 OK → Обработка

Ключевые параметры, которые влияют на надёжность:

- Retry policy: большинство платформ (Shopify, WooCommerce, СДЭК, ЮKassa) повторяют доставку при неуспехе. Стандарт — 5 попыток с экспоненциальной задержкой: 1 мин → 5 мин → 30 мин → 2 ч → 12 ч.

- Timeout: типичное окно ожидания ответа — 5 секунд. Если ваш сервер не ответил за это время, вебхук считается неуспешным.

- Подпись (HMAC): payload подписывается секретным ключом. Проверка подписи обязательна — иначе злоумышленник может подделать «оплату заказа».

- Идемпотентность: одно событие может прийти дважды. Ваш обработчик должен распознавать дубли по event_id или order_id + status.

Пример payload для события order.paid:

{
  "event": "order.paid",
  "event_id": "evt_9f3a2b",
  "created_at": "2025-03-14T10:22:41Z",
  "order": {
    "id": 482913,
    "total": 7490,
    "currency": "RUB",
    "customer_email": "client@example.ru"
  }
}

Сравнительная таблица: Webhook vs Polling vs API-запрос

Применение в DTC и e-commerce

1. Синхронизация заказов с WMS. Магазин на Shopify/InSales получает order.created → вебхук летит на складскую систему → через 2–4 секунды заказ уже в очереди на сборку. Без вебхука средняя задержка при polling раз в 5 минут — до 300 секунд, а при пиковых нагрузках (распродажа 11.11) — до 15 минут.

2. Трекинг доставки. Служба доставки (СДЭК, Boxberry, Почта России) отправляет событие status.changed → клиент получает push/SMS «Заказ в пункте выдачи». Конверсия в повторную покупку у брендов с real-time трекингом выше на 18–24% (данные Klaviyo, 2024).

3. Платёжные события. ЮKassa, CloudPayments, Stripe шлют payment.succeeded → заказ автоматически переводится в статус «Оплачен» → запускается триггерное письмо. Задержка обработки платежа сокращается с 60 секунд (ручная сверка) до 1,5 секунды.

4. Маркетинговые триггеры. cart.abandoned → вебхук в CRM → через 30 минут уходит письмо «Забыли что-то?». По статистике Omnisend, такие письма возвращают от 8 до 14% брошенных корзин.

5. Обновление остатков. inventory.updated → вебхук в PIM/ERP → данные на сайте и в маркетплейсах синхронны. При 5 000 SKU и polling каждые 10 минут вы делаете 720 000 запросов/мес; с вебхуками — только фактические изменения, обычно ~40 000/мес.

Частые ошибки

- Нет проверки подписи. Любой может отправить фейковый order.paid. Всегда валидируйте HMAC-заголовок.

- Долгая обработка в основном потоке. Если ваш эндпоинт ставит задачу в очередь, а не обрабатывает синхронно, вы избежите timeout-ошибок.

- Игнорирование идемпотентности. Дубли приводят к двойным списаниям, двойным письмам, двойной отгрузке.

- Отсутствие логирования. Без хранения входящих payload невозможно разобрать инцидент «заказ не ушёл на склад».

- Публичный URL без HTTPS. Многие платформы (Stripe, Shopify) просто не отправят вебхук на http://.

- Забыли про retry. Если ваш сервер упал на 10 минут, события не потеряются — но только если вы отвечаете 2xx при повторной доставке.

- Один эндпоинт на всё. Разделяйте orders, payments, shipping — так проще масштабировать и отлаживать.

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

- API — интерфейс, через который вы сами запрашиваете данные; вебхук — его «зеркало» для событий.

- Polling — противоположный подход: регулярные запросы вместо push-уведомлений.

- Callback URL — адрес, на который приходит вебхук.

- HMAC-подпись — криптографическая проверка подлинности запроса.

- Идемпотентность — свойство обработчика не создавать дубли при повторе.

- Event-driven architecture — архитектура, построенная на событиях, где вебхуки — базовый транспорт.

- Middleware / очередь (RabbitMQ, Kafka) — буфер между приёмом вебхука и его обработкой.

- Rate limit — ограничение на число запросов; вебхуки помогают его не превышать.