Вебхуки МойСклад: синхронизация заказов и остатков в реальном времени

Почему вебхуки лучше частого polling

Официальный workbook МойСклад рекомендует вебхуки для взаимодействия интернет-магазина или приложения с аккаунтом в реальном времени и снижения количества периодических запросов. Это особенно полезно для новых заказов, изменений статуса, отгрузок и обновления карточек.

Но polling полностью не исчезает. Периодическая сверка нужна как страховка от временной недоступности endpoint, ошибок обработки и изменений конфигурации.

Надежная схема обработки события

1. Endpoint принимает POST и проверяет структуру запроса.
2. Сохраняет минимальные данные события и уникальный ключ.
3. Быстро возвращает успешный HTTP-ответ.
4. Worker получает актуальную сущность по API.
5. Применяет бизнес-правила и обновляет внешнюю систему.
6. Фиксирует результат и контрольную точку.

Требования к endpoint

• HTTPS. Публичный адрес с действующим сертификатом.
• Быстрый ответ. Не ждите внутри запроса медленную CRM, маркетплейс или генерацию документов.
• Идемпотентность. Повтор одного события не должен повторно создавать заказ или списание.
• Безопасные логи. Не записывайте токены и лишние персональные данные.
• Контроль нагрузки. Ограничивайте параллелизм worker и соблюдайте лимиты JSON API.

POST /webhooks/moysklad
1. validate payload
2. save event key
3. enqueue entity refresh
4. return 200

worker:
5. GET current entity from JSON API
6. upsert external record
7. mark event processed

Дубли, порядок и гонки

Один объект может измениться несколько раз подряд. Событие о старом состоянии способно обрабатываться после нового, если задачи выполняются параллельно. Поэтому worker должен получать актуальный объект, сравнивать версию или момент обновления и не применять устаревшие данные поверх новых.

Для защиты от дублей используйте уникальность по идентификатору события, а для результата — upsert по ID сущности МойСклад. Название товара, номер телефона или номер документа не являются надежным техническим ключом.

Почему нужна периодическая сверка

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

Что контролировать в production

• Количество полученных и обработанных событий.
• Возраст самой старой задачи в очереди.
• Число повторов и dead-letter задач.
• Ответы 429 и 5xx от API МойСклад.
• Расхождения периодической сверки.
• Время от изменения в МойСклад до обновления внешней системы.

Практический пример: интернет-магазин

После изменения заказа webhook ставит задачу на обновление. Worker получает заказ и позиции через API, сопоставляет товары по сохраненным ID, обновляет статус в магазине и фиксирует версию. Если магазин недоступен, задача повторяется. Если событие потерялось, заказ попадет в следующую сверку.

Такую схему мы используем при интеграции МойСклад с интернет-магазином: вебхуки обеспечивают скорость, а сверка и идемпотентность — надежность.

Вывод

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