🪝 Веб-хуки
Что такое веб-хуки?
Веб-хуки — это механизм автоматического уведомления вашего сайта об изменениях в МойСклад. Когда в МойСклад происходят изменения (обновление заказа, создание оплаты, отгрузки и т.д.), МойСклад автоматически отправляет уведомление на ваш сайт.
Настройка веб-хуков обязательна для корректной работы модуля. Без веб-хуков изменения заказов из МойСклад не будут передаваться на сайт.
Зачем нужны веб-хуки?
- Мгновенная синхронизация (либо через очередь) — изменения передаются сразу после их создания в МойСклад
- Автоматическое обновление заказов — статусы, комментарии и другие данные обновляются без задержек
- Снижение нагрузки — система работает по событиям, а не постоянно опрашивает API
Какие веб-хуки поддерживает модуль
| Сущность МойСклад | События | Зачем нужен |
|---|---|---|
customerorder (заказ покупателя) | UPDATE | Обязательный. Перенос изменений заказа из МойСклад на сайт |
customerorder (заказ покупателя) | CREATE | Импорт новых заказов из МойСклад на сайт |
paymentin (входящий платёж) | CREATE, UPDATE, DELETE | Полный обмен оплатами [full] |
cashin (приходный ордер) | CREATE, UPDATE, DELETE | Полный обмен оплатами [full] |
demand (отгрузка) | CREATE, UPDATE | Полный обмен отгрузками [full] |
Подробнее о каждом веб-хуке — в разделе Структура веб-хука и создание веб-хука.
Удаление заказа покупателя и удаление отгрузки в МойСклад модуль на сайт не переносит: веб-хуков customerorder / DELETE и demand / DELETE во вкладке нет, а если такое уведомление всё же придёт, модуль его пропустит.
Как модуль обрабатывает веб-хук
- МойСклад отправляет уведомление на адрес веб-хука (по умолчанию
https://site.ru/mshooks/hook.php). В адресе передаётся проверочная строка — см. Настройка URL. - Модуль проверяет запрос. Уведомление обрабатывается, только если включена опция «Включить обмен» (вкладка Работа модуля) и проверочная строка совпала. Запросы с неверной проверочной строкой молча отклоняются и в журнал не пишутся. МойСклад сразу получает ответ об успешном приёме, дальнейшая обработка идёт уже на стороне сайта.
- Модуль распределяет изменения. В одном веб-хуке может прийти несколько изменённых сущностей (например, при массовом редактировании). Каждая из них в зависимости от типа выполнения веб-хука обрабатывается сразу или ставится в очередь задач. Сколько сущностей обработать сразу, задаёт ограничение, остальные тоже уходят в очередь.
- Очередь разбирает агент — по расписанию он берёт порцию задач и обрабатывает их так же, как при моментальном выполнении.
Дополнительно модуль:
- отсекает повторы — одно и то же изменение (сущность + событие), пришедшее повторно в течение нескольких секунд, обрабатывается один раз. Время задаётся опцией «Кеш веб-хука (секунды)» во вкладке Прочее (от 1 до 10 секунд, по умолчанию 5);
- пропускает заказы, для которых обмен отключён, и заказы, которых нет на сайте (если это не импорт нового заказа);
- пишет журнал по каждой обработанной сущности: в заголовке записи указаны тип сущности, событие, идентификатор в МойСклад и, если заказ на сайте найден, его номер.
Изменения заказа из веб-хука записываются от имени пользователя из опции «Пользователь, под которым записываем изменения заказа» (вкладка Работа модуля). Модуль авторизует этого пользователя только на время обработки и после неё снимает только ту авторизацию, которую выдал сам. Если запрос пришёл в рамках сессии уже авторизованного пользователя сайта, его сессия не завершается.
Разделы настройки
В данном разделе доступны следующие настройки:
- Настройка URL — адрес для получения веб-хуков и проверочная строка
- Ограничения веб-хуков — лимиты обработки сущностей и очереди задач
- Структура веб-хука и создание веб-хука — создание, обновление и удаление веб-хуков, выбор типа выполнения