Вебхуки в интернет-магазине: как передавать заказы без постоянного опроса API

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

Как работает вебхук#

В классическом сценарии магазин публикует endpoint — URL, который принимает HTTP POST. Внешняя система отправляет туда JSON с событием. Обработчик проверяет авторизацию, сохраняет сообщение, ставит задачу в очередь и возвращает код успеха.

Например, сообщение о новом заказе может выглядеть так:

{
  "event_id": "evt_20260903_000184",
  "event": "order.created",
  "version": 1,
  "occurred_at": "2026-09-03T10:15:00Z",
  "order_id": "order-48392",
  "source": "online-store"
}

Не обязательно передавать в вебхуке весь заказ. Чем меньше сообщение, тем проще его повторить и принять. После получения уведомления обработчик может запросить детали заказа через API, проверить текущий статус и передать данные в CRM, 1С или службу доставки.

Вебхук и опрос API: что выбрать#

Опрос API удобен, когда внешняя система не умеет отправлять события или когда нужно регулярно сверять состояние. Его недостатки — задержка, лишняя нагрузка и сложность выбора интервала: слишком частые запросы расходуют лимиты, слишком редкие задерживают обработку.

Вебхук лучше подходит для событий, где важна скорость: успешная оплата, новый заказ, отмена, возврат. Но он зависит от доступности принимающего endpoint и требует защиты от повторов.

Наиболее практичная схема — гибридная:

1. Вебхук сообщает, что объект изменился.
2. Очередь ставит событие в обработку.
3. Сервис получает актуальную запись через API.
4. После обработки ночная сверка API ищет пропущенные события.

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

Какие события передавать#

Не начинайте с десятков уведомлений. Составьте карту процессов и выделите события, которые запускают действие в другой системе:

• order.created — создать сделку или заказ в CRM;
• payment.succeeded — подтвердить оплату и запустить сборку;
• order.cancelled — остановить отгрузку;
• shipment.created — передать отправление в доставку;
• order.delivered — запустить коммуникацию после покупки;
• return.created — создать задачу на проверку возврата;
• product.updated — обновить остатки и цену в каналах продаж.

Названия событий должны быть однозначными. Не называйте одно событие order.update, если оно используется и для оплаты, и для адреса, и для смены статуса. Получателю будет трудно понять, какое действие нужно выполнить.

Четыре обязательные проверки#

1. Авторизация и подпись#

Закрытый URL сам по себе не является защитой. Используйте секретный токен, подпись тела запроса или взаимную аутентификацию, если это поддерживают обе стороны. Секреты храните в переменных окружения, а не в коде и не в логах.

Проверяйте подпись на исходном теле запроса до его преобразования. Заодно ограничьте размер сообщения, разрешённые методы и сетевые правила. Публичный endpoint должен принимать только то, что действительно нужно интеграции.

2. Идемпотентность#

Отправитель может повторить событие, если не получил ответ вовремя. Обработчик должен сохранить event_id или комбинацию event + object_id + version и понять, обрабатывалось ли сообщение раньше.

Например, повторный payment.succeeded не должен второй раз создавать чек или отправлять клиенту дублирующее письмо. Повторную доставку можно вернуть как успешную, если исходная операция уже завершена.

3. Повторы и очередь#

Не выполняйте долгие операции прямо в HTTP-запросе. Приняли и проверили сообщение — записали его в очередь — ответили отправителю. Дальше отдельный обработчик обращается к CRM или 1С, повторяет временные ошибки и фиксирует окончательный результат.

Для повторов задайте ограничение и задержку: например, несколько попыток с увеличивающимся интервалом. Ошибки авторизации, неверную схему и отсутствие обязательного поля не нужно бесконечно повторять — такие сообщения отправляются в dead-letter очередь на разбор.

4. Порядок событий#

События могут прийти не в том порядке, в котором произошли. Сначала может прийти order.cancelled, а затем задержавшийся order.created. Добавляйте время события и версию объекта, а обработчик пусть сравнивает их с уже сохранённым состоянием.

Если порядок критичен, сериализуйте события по ID заказа. Для менее строгих процессов достаточно повторно запросить актуальное состояние по API перед изменением записи.

Как спроектировать формат события#

Сделайте общий конверт для всех событий: event_id, тип события, версия, время, источник и идентификатор объекта. Не меняйте смысл поля без увеличения версии схемы. Новые необязательные поля добавляйте обратно совместимо, а несовместимые изменения выпускайте как version: 2.

В логах сохраняйте метаданные, но маскируйте персональные и платёжные данные. Для диагностики обычно достаточно ID заказа, типа события, времени, кода ответа, числа попыток и причины ошибки.

Как внедрить вебхуки в магазине#

1. Опишите цепочку: какое событие возникает, кто его получает и какое действие запускается.
2. Выберите владельца события — систему, где хранится актуальное состояние.
3. Зафиксируйте JSON-схему, авторизацию и правила повторной доставки.
4. Сделайте endpoint, который быстро валидирует и ставит сообщение в очередь.
5. Добавьте таблицу или хранилище обработанных event_id.
6. Протестируйте повторы, таймауты, неправильную подпись, нарушенный порядок и недоступность CRM.
7. Настройте журнал, метрики очереди и уведомление о сообщениях в dead-letter.
8. Запустите сначала одно событие, сравните данные с источником и только потом расширяйте интеграцию.

Для связки магазина с 1С-Битрикс, CRM и сервисами доставки этот порядок важнее конкретного конструктора интеграций. Готовый модуль ускоряет старт, но не отменяет проверку дублей, ошибок и расхождений статусов.

Вебхук — это транспорт уведомления, а не полноценная интеграционная архитектура. Надёжная схема сочетает понятный контракт событий, защищённый endpoint, очередь, повторную обработку и сверку через API. Тогда автоматизация экономит время и не превращается в источник незаметных пропущенных заказов.