Вебхуки: настройка уведомлений

Вебхуки — это способ заставить МойСклад самому сообщать внешним системам о том, что произошло: создан заказ, изменён остаток, проведена отгрузка. Вместо постоянного опроса API ваш сервис получает POST-запрос в момент события. Разбираем, как их настроить и не наступить на грабли.

Что такое вебхук и чем он лучше опроса

Вебхук (webhook) — это HTTP-запрос, который МойСклад отправляет на указанный вами адрес, когда наступает подписанное событие. Это модель «не звони нам, мы сами позвоним»: система инициирует связь, а не ждёт запроса.

Сравним два подхода к интеграции:

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

На какие события можно подписаться

Вебхук привязывается к сущности (entity) и типу действия. Сущность — это тип объекта в МойСклад, а действие — что с ним произошло.

Основные типы действий:

• CREATE — создан новый объект;
• UPDATE — объект изменён;
• DELETE — объект удалён.

Подписаться можно на широкий круг сущностей — заказы покупателей (customerorder), отгрузки (demand), приёмки (supply), товары (product), контрагентов (counterparty), платежи и другие документы. Для каждой пары «сущность + действие» создаётся отдельный вебхук.

Как настроить вебхук

Вебхуки настраиваются двумя способами: через интерфейс аккаунта и через JSON API. В интерфейсе путь — Настройки → Обмен данными → Вебхуки. Порядок действий одинаков для обоих способов.

1. Укажите URL обработчика — публично доступный адрес вашего сервиса, обязательно по HTTPS.
2. Выберите сущность и тип действия.
3. Сохраните и убедитесь, что вебхук активен.

Через API вебхук создаётся POST-запросом к ресурсу /entity/webhook с телом, где заданы поля url, action и entityType. Для авторизации используется токен доступа.

Что приходит в теле запроса

МойСклад отправляет на ваш URL POST-запрос с JSON. В теле — не полный объект, а компактное уведомление: тип события, тип сущности и ссылка (meta.href) на изменённый объект. Полные данные забираются отдельным GET-запросом по этой ссылке.

Упрощённо структура выглядит так:

{ "events": [ { "meta": { "href": "...customerorder/ID", "type": "customerorder" }, "action": "CREATE" } ] }

Ключевые моменты обработки:

• События приходят пачками. В одном запросе массив events может содержать несколько изменений — обрабатывайте их в цикле.
• Нужен быстрый ответ. Обработчик должен вернуть код 200 сразу, а тяжёлую логику вынести в фоновую очередь.
• Данные догружаются. Чтобы получить состав заказа, суммы и статусы, сделайте GET по meta.href.

Надёжность: повторы, дубли и таймауты

Сеть ненадёжна, поэтому вебхуки требуют аккуратной обработки на стороне приёмника. Если ваш сервер не ответил вовремя или вернул ошибку, МойСклад повторит доставку. Это защищает от потерь, но порождает риск дублей.

• Идемпотентность. Обрабатывайте одно и то же событие безопасно при повторе — храните признак уже обработанных объектов, чтобы не создать две записи.
• Таймаут. Долгий обработчик воспринимается как недоступный. Отвечайте 200 быстро, работу делайте асинхронно.
• Логирование. Пишите входящие запросы в журнал — это единственный способ разобраться, почему событие «не дошло».
• Отключение при сбоях. Если обработчик стабильно недоступен, вебхук может быть автоматически деактивирован — следите за его статусом.

Вебхуки и внутренние уведомления — не одно и то же

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

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

Итог

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

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