Вебхуки склада: статусы заказов в вашу систему

Вебхук склада — это запрос, который фулфилмент сам отправляет в вашу систему, когда что-то изменилось: приёмка завершена, заказ FBS собран, поставка передана. Вместо того чтобы каждую минуту спрашивать склад «что нового?», вы получаете событие через несколько секунд после действия на складе. Ниже — как это устроено, какие события бывают, как проверить подпись и не обработать одно событие дважды, и что делать, если ваш сервер на час упал.

Описание основано на нашей открытой документации API (v1.1). Принцип одинаков для любой системы: 1С, МойСклад, CRM, ERP, репрайсера или собственной разработки — нужен только адрес, который принимает POST-запросы по HTTPS.

Зачем вебхуки, если есть опрос

Опрос — самый простой способ: раз в N минут вызвать метод и сравнить результат с прошлым. Он работает, но у него три слабых места.

1. 1Задержка. При опросе раз в 5 минут вы узнаёте о событии в среднем через 2,5 минуты, в худшем случае — через 5. Для статуса «заказ собран» это некритично, для «заявка на приёмку подтверждена» тоже, но для отмены заказа или остатка, который нужно срочно снять с витрины, — заметно.
2. 2Лишняя нагрузка. Из 288 опросов в сутки (раз в 5 минут) подавляющее большинство возвращает «ничего не изменилось». Вы платите за них своим временем разработки, а сервер оператора — ресурсами.
3. 3Сложность сравнения. Чтобы понять, что изменилось, нужно хранить прошлое состояние и сравнивать. При вебхуке событие само говорит, что произошло, и в случае смены статуса приходит вместе с предыдущим статусом.

У вебхуков свои слабые места: они могут прийти не по порядку, могут прийти дважды, а ваш сервер может быть недоступен в момент отправки. Поэтому правильная схема — вебхуки как основной канал плюс редкий резервный опрос для страховки. Про остатки и их синхронизацию с площадками мы писали в статье «Остатки FBS: как не продать товар, которого нет».

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

Подписаться можно на отдельные события. Для селлера FBS и FBO нужны шесть рабочих событий:

: События вебхуков склада

Ещё есть служебное событие webhook.ping — его склад отправляет при создании подписки и по ручному вызову, чтобы проверить адрес. Подробнее о каждом событии и его данных — в справочнике вебхуков.

Как подключить за 10 минут

Рабочий порядок такой:

1. 1Получите ключ API в кабинете и проверьте его одним запросом на чтение — например, запросом данных о себе.
2. 2Поднимите на своей стороне адрес, который принимает POST и сразу отвечает кодом 2xx. На первом этапе можно просто записывать тело запроса в журнал.
3. 3Зарегистрируйте подписку одним запросом: адрес и список событий. При создании склад сразу отправляет на ваш адрес тестовое событие и ждёт ответ 2xx до 10 секунд. Если адрес не ответил, подписка не создаётся — так нельзя подписаться на чужой или временно недоступный адрес.
4. 4В ответе на создание вы получите секрет подписи. Он показывается один раз: сохраните его в хранилище секретов сразу. Потеряли — удалите подписку и создайте новую.
5. 5Отправьте тестовое событие вручную и убедитесь, что оно появилось в журнале и подпись проходит проверку.
6. 6Переведите обработку на реальные события и оставьте резервный опрос раз в 15–30 минут.

Лимит — 10 подписок на клиента, этого хватает, чтобы разделить, например, учётную систему, CRM и аналитику. Для отладки можно не терять время на реальные заказы: есть песочница, в которой данные и события тестовые.

Как выглядит событие

Каждое событие — отдельный POST с телом в формате JSON и служебными заголовками:

• тип события,
• идентификатор доставки (у каждой попытки отправки он свой),
• время отправки в формате unix,
• подпись.

В теле: идентификатор события, тип, время события и данные. Для событий смены статуса данные — это объект (приёмка, отгрузка или заказ) в том виде, как его вернул бы обычный запрос на чтение, плюс поле с предыдущим статусом. Благодаря этому не нужно хранить историю статусов у себя: если заказ перешёл из «собирается» в «отменён», это видно из одного события.

Пример приёмки с расхождением. Склад завершил приёмку и отправил событие receipt.completed со статусом «принято с расхождением» и числом недостающих единиц, допустим 120. Ваша система получает его, создаёт задачу сверке и запрашивает акт. Ни опроса, ни ожидания вечернего отчёта. О том, как потом разбираться с недостачей, смотрите в статье про недостачу на приёмке WB и в гайде по сверке недостач.

Подпись: как убедиться, что запрос от склада

Адрес вебхука открыт для интернета, поэтому любой может отправить на него поддельное «заказ отменён». Защита — подпись. Склад считает HMAC-SHA256 от строки «время, точка, тело запроса» с вашим секретом и кладёт результат в заголовок. Ваш обработчик повторяет вычисление и сравнит значения.

Три правила, которые чаще всего нарушают:

1. 1Считайте подпись от сырого тела запроса, байт в байт, как оно пришло. Если сначала разобрать JSON, а потом собрать его заново, порядок полей, пробелы и форматирование чисел могут измениться, и подпись «не сойдётся». В веб-фреймворках для адреса вебхука нужно подключить чтение сырого тела.
2. 2Сравнивайте подписи функцией с постоянным временем сравнения, а не обычным знаком равенства.
3. 3Проверяйте время в заголовке: если запросу больше нескольких минут, отклоняйте его — так вы защищаетесь от повторной отправки перехваченного запроса.

В документации есть готовые примеры проверки на Python, PHP и Node.js, а для 1С логика та же — любой язык с HMAC-SHA256 справится.

Повторы и идемпотентность: почему событие может прийти дважды

Склад считает доставку успешной, если ваш адрес ответил кодом 2xx в течение 10 секунд. Иначе (другой код, таймаут, хост недоступен) включается график повторов: через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов. После восьмой подряд неудачи подписка автоматически отключается, а новые события по ней не отправляются. Включить её можно, только создав подписку заново.

Из этого следует несколько практических выводов.

• Отвечайте быстро. Ответ 200 сразу после проверки подписи и записи события в очередь, а обработка — в отдельном процессе. Если обработчик делает тяжёлые операции до ответа, вы получите повторы просто из-за таймаута.
• Обрабатывайте событие идемпотентно. Один и тот же идентификатор события может прийти дважды, например после сбоя с нашей стороны. Храните идентификаторы обработанных событий и пропускайте повторы. Проще всего — таблица с уникальным индексом по этому идентификатору: вторая вставка падает, и вы понимаете, что событие уже было.
• Не рассчитывайте на порядок. Событие «заказ отгружен» теоретически может обогнать «заказ собран». Если порядок важен, сравнивайте с предыдущим статусом из данных события или с временем события, а не со временем получения.
• Следите за состоянием подписки. Если ваш сервер лежал сутки, подписка могла отключиться. Проверяйте её раз в день запросом списка подписок.

Дополнительная страховка: раз в несколько минут склад сам сверяет состояние целиком, чтобы изменение, о котором не удалось сообщить, всё равно дошло (пусть и с задержкой). Но писать обработчик нужно из расчёта «событие придёт, но порядок и точный момент не гарантируются».

Журнал доставок: когда «ничего не пришло»

Частый вопрос на старте — «почему тишина?». Есть журнал доставок: по каждой подписке видны попытки, их статус и тело отправленного события. Типичные причины, по которым события не доходят:

1. 1Файрвол или защита на вашей стороне блокирует запросы с неизвестных адресов.
2. 2Адрес отвечает редиректом, а не кодом 2xx: например, с http на https или добавляется слэш в конце.
3. 3Обработчик отвечает 200 только после долгой операции, и склад считает это таймаутом.
4. 4Подпись не проходит из-за разобранного и пересобранного тела запроса, и ваш код возвращает 401 — склад воспринимает это как неудачу.
5. 5Подписка отключена после серии неудач.

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

Пример архитектуры для FBS: от события до CRM

Типичная схема для продавца на Wildberries или Ozon с FBS выглядит так:

1. 1Заказ приходит с площадки на склад, где его собирают и упаковывают. О схеме FBS подробнее — на странице FBS.
2. 2На каждой смене статуса склад отправляет событие смены статуса заказа.
3. 3Ваш приёмник проверяет подпись, кладёт событие в очередь и отвечает 200.
4. 4Воркер читает очередь, проверяет идентификатор в таблице обработанных, обновляет статус в CRM или в учётной системе и, если заказ отменён, снимает остаток с витрины.
5. 5Раз в 15–30 минут резервный опрос сравнивает список активных заказов с вашей системой и закрывает расхождения.

Эта схема подходит и для FBO: вместо заказов вы подписываетесь на события приёмок и отгрузок, а остатки подтягиваете по запросу. Разницу схем и то, когда выгодна каждая, мы разбирали в статье «FBO или FBS: что выбрать в 2026», а условия по поставкам на склады маркетплейсов — на странице FBO.

Что хранить у себя и как не потерять историю

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

1. 1Идентификатор события — для защиты от дублей.
2. 2Тип и время события на стороне склада — для разбора порядка.
3. 3Сырое тело запроса за последние 30–90 дней — чтобы при споре показать, что именно пришло.
4. 4Результат обработки: применено, пропущено как дубль, ошибка и текст ошибки.

Посчитайте нагрузку на цифрах. Продавец с 300 заказами FBS в день при четырёх сменах статуса на заказ получает около 1 200 событий заказов в сутки, то есть меньше одного в минуту в среднем. Добавьте приёмки и отгрузки — ещё несколько десятков. Такой поток не требует отдельной инфраструктуры: хватит одной таблицы и одного воркера. Сложности начинаются не от объёма, а от пиков: после перезапуска вашего сервера накопившиеся повторы приходят пачкой, и обработчик должен выдерживать их, не блокируясь.

Отдельно продумайте поведение на ошибках. Если ваша система приняла событие, но не смогла применить его (например, в CRM нет такого заказа), не возвращайте ошибку складу: ответ 2xx означает «получил», а не «применил». Запишите проблемное событие в отдельную очередь на разбор и верните 200, иначе склад начнёт слать повторы того, что всё равно не обработается.

Типичные ошибки

• Принять вебхук и сделать всю работу до ответа. Результат — таймауты, повторы и отключённая подписка.
• Парсить JSON и проверять подпись по пересобранной строке.
• Не хранить идентификаторы событий и дважды списывать остаток.
• Опираться только на вебхуки без резервного опроса.
• Хранить секрет в коде или в общем чате.
• Не мониторить отключение подписки.
• Тестировать на реальных данных вместо песочницы.

Что вы получаете как селлер

Автоматизация нужна не ради самой интеграции. Конкретные выгоды: статус заказа в CRM появляется за секунды, а не к вечернему отчёту; приёмка с расхождением сразу превращается в задачу для менеджера; отмена заказа вовремя снимает товар с витрины, и вы не получаете лишний штраф за просрочку. Подробный перечень того, что ещё можно автоматизировать, — в статье «API Wildberries и Ozon: что селлер может автоматизировать».

Вывод

Вебхуки превращают склад из «чёрного ящика, который надо опрашивать» в источник событий для вашей системы. Для надёжной работы достаточно пяти практик: быстрый ответ 2xx, проверка подписи по сырому телу, идемпотентная обработка, мониторинг подписки и редкий резервный опрос. Всё это одинаково работает с любой системой на вашей стороне.

Хотите попробовать без риска — откройте песочницу и документацию API, а как данные выглядят в кабинете, можно посмотреть в демо без регистрации. Если вы подбираете оператора, у которого интеграция и учёт каждой единицы входят в базовую работу, посмотрите, как мы работаем по SLA, и напишите нам список SKU — рассчитаем стоимость по тарифам.