Вебхуки JSON API

Вебхуки JSON API 1.2 МойСклад заменяют постоянный опрос данных: сервис сам отправляет POST на ваш URL при изменении сущности. Это основа событийной интеграции — заказ создан, товар изменён, документ удалён.

Что такое вебхук и зачем он нужен

Вебхук — это подписка на события над сущностью определённого типа. Вместо того чтобы каждые несколько минут дёргать GET /entity/customerorder и сравнивать данные, вы регистрируете подписку, и МойСклад присылает уведомление в момент изменения.

• Снижается нагрузка и расход лимитов API.
• Данные приходят почти в реальном времени.
• Логика становится событийной: получил уведомление — обработал конкретную сущность.

Регистрация подписки

Вебхуки — это сущность webhook, управляется через CRUD:

POST https://api.moysklad.ru/api/remap/1.2/entity/webhook

{"url":"https://site.ru/hooks/moysklad","action":"UPDATE","entityType":"customerorder"}

Ключевые поля подписки:

Одна подписка = одна пара «событие + тип». На UPDATE, CREATE и DELETE заказа нужны три отдельных вебхука.

Формат уведомления

МойСклад присылает POST с телом, где в массиве events перечислены произошедшие события:

{"events":[{"meta":{"href":".../entity/customerorder/ID","type":"customerorder"},"action":"UPDATE","accountId":"...","updatedFields":["sum","state"]}],"auditContext":{...}}

• action — тип события.
• meta.href — ссылка на сущность, по которой делается GET за деталями.
• updatedFields — приходит, если у подписки задан diffType: FIELDS.

В одном POST может прийти несколько событий, если изменения произошли пачкой — обрабатывайте массив в цикле, а не только первый элемент. Тип сущности в meta.type позволяет одному приёмнику маршрутизировать разные объекты. Поле auditContext связывает событие с записью аудита и показывает, кто и в каком контексте внёс изменение — это полезно, чтобы отличать правки оператора от изменений, сделанных вашей же интеграцией, и не зацикливать обмен.

Ответ приёмника и повторные доставки

Ваш обработчик обязан ответить HTTP 200 быстро (в пределах нескольких секунд). Если ответа нет, код не 2xx или таймаут — МойСклад повторяет доставку с нарастающими интервалами.

• Не выполняйте тяжёлую обработку синхронно в обработчике — примите событие, поставьте в очередь, верните 200.
• Если приёмник долго недоступен, подписка может быть автоматически отключена.
• Повторные доставки означают, что одно и то же событие может прийти несколько раз.

Безопасность приёмника

URL вебхука публичный, поэтому его нужно защищать от подделки запросов:

1. Принимайте вебхуки только по HTTPS.
2. Добавьте в URL сложный секретный сегмент или query-параметр-токен, который знаете только вы.
3. Проверяйте accountId в теле — он должен совпадать с вашим аккаунтом МойСклад.
4. Ограничьте приём по списку исходящих IP, если он у вас зафиксирован.

Так вы отсекаете мусорные и вредоносные запросы ещё до бизнес-логики.

Управление и лимиты подписок

Список подписок — GET /entity/webhook, удаление — DELETE /entity/webhook/{id}, временное отключение — PUT с полем enabled: false. Учитывайте ограничения:

• Количество вебхуков на аккаунт ограничено (порядка нескольких десятков), не плодите лишние подписки.
• Отключённые подписки не удаляются сами — чистите их при переустановке интеграции.
• Тестируйте приёмник до продакшена, например через временный туннель, чтобы не ловить массовые повторы на сломанном URL.
• При переносе интеграции между стендами меняйте url подписки, а не заводите новую поверх старой — иначе события будут дублироваться на два адреса.

Хорошая практика — хранить список активных подписок в конфигурации интеграции и при старте сверять его с фактическим состоянием через GET /entity/webhook, восстанавливая недостающие и удаляя лишние вебхуки автоматически.

Итог

Вебхуки — это подписки на события CREATE/UPDATE/DELETE по типу сущности. Они присылают только meta и тип события, дают возможные дубли и требуют быстрого ответа 200 с последующей обработкой через очередь. Защищайте URL секретом и проверяйте accountId, а логику стройте идемпотентно.

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