Событие пропущенного веб-хука

[OnWebhookSkipped] Веб-хук по сущности, которую модуль обрабатывать не стал

Доступно с версии 3.9.0

На более ранних версиях событие не вызывается.

Событие OnWebhookSkipped — пара к OnWebhookUpdate. Если OnWebhookUpdate срабатывает, когда элемент найден или создан, то OnWebhookSkipped срабатывает в противоположном случае: веб-хук пришёл, модуль его разобрал, но элемент в каталоге не загрузил и дальше обрабатывать не стал.

Так бывает, когда:

• элемента нет в каталоге Битрикс, а создавать его по веб-хуку настройки не разрешают;
• сущность архивная;
• сущность не проходит фильтр по доп. полю;
• сущность лежит вне групп товаров, выбранных в настройках импорта;
• объект сущности не удалось загрузить из МойСклад (сетевая ошибка, сущность уже удалена);
• для группы товаров — не задан инфоблок групп или раздела нет в каталоге.

примечание

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

До появления этого события такой веб-хук не оставлял кастомному коду ни одного сигнала.

к сведению

Событие информационное, возвращать ничего не нужно. Отменить или изменить поведение модуля через него нельзя.

Когда событие не вызывается

Случай	Почему
Действие DELETE	Удаление идёт своим путём и своим событием — OnBeforeDeleteItem
Сущность specialpricediscount (скидки)	У скидок другой путь обработки, объект сущности там не создаётся
Сущность productfolder при выключенном импорте групп	Модуль групп не трогает и до разбора не доходит
Веб-хук отсечён дедупликацией кеша или настройками до разбора	Модуль до этой точки не доходит
href не принадлежит API МойСклад или действие не из CREATE, UPDATE, DELETE	Веб-хук отбрасывается до разбора
Сущность объявлена в реестре OnBuildWebhookEntityList в режиме replace или обработчик before отменил обработку	Модуль сущность не обрабатывает
Модификации при включённой опции загрузки модификаций агентом	Веб-хук по variant пропускается раньше
Событие не попало в первые webhook_limit_count событий запроса	До разбора оно не дошло; такие события приходят в OnWebhookEventsDropped

Исключения не перехватываются

Исключение из обработчика модуль не ловит: оно обрывает обработку остальных событий этого веб-хука. Оборачивайте свой код в try/catch.

Частота срабатывания

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

Описание события

Параметры события

Параметр	Тип	Описание
hook	object	Объект веб-хука от МойСклад целиком
entity	string	Сущность: product, variant, bundle, service, productfolder
action	string	Действие веб-хука: CREATE или UPDATE
ms_element	object | null	Сущность из МойСклад. null, если объект не удалось загрузить из API

предупреждение

ms_element может быть null — именно в этом случае модуль и не смог ничего сделать. Проверяйте значение перед обращением к свойствам.

Возвращаемое значение

Ничего возвращать не нужно.

Пример вызова события

//Пример кода нужно вставить в файл init.php

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnWebhookSkipped',
    'OnWebhookSkippedHandler'
);

function OnWebhookSkippedHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();

    // $hook — объект веб-хука МойСклад:
    // $hook->action      // 'CREATE' | 'UPDATE'
    // $hook->meta->type  // 'product' | 'variant' | 'bundle' | 'service'
    // $hook->meta->href  // 'https://api.moysklad.ru/api/remap/1.2/entity/product/...'
    $hook = $eventParams['hook'];

    $entity = $eventParams['entity']; // тип сущности МойСклад
    $action = $eventParams['action']; // CREATE или UPDATE

    // $msElement — сущность из МойСклад либо null, если объект не загрузился
    // $msElement->name         // 'Название товара'
    // $msElement->externalCode // 'abc123externalcode'
    // $msElement->archived     // true
    // $msElement->pathName     // 'Каталог/Обувь'
    $msElement = $eventParams['ms_element'];

    if ($msElement === null) {
        // объект из МойСклад загрузить не удалось
        return;
    }

    #WORK_AREA#
}

Примеры использования

Создание элемента своими силами

Модуль создавать элемент не стал, а кастомной логике он нужен.

function OnWebhookSkippedHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();
    $msElement = $eventParams['ms_element'];

    if ($msElement === null || $eventParams['entity'] !== 'product') {
        return;
    }

    // Архивные всё равно пропускаем
    if (!empty($msElement->archived)) {
        return;
    }

    // Создание элемента — на стороне разработчика
    YourProductCreator::createFromMs($msElement);
}

Мониторинг: сколько веб-хуков уходит в никуда

function OnWebhookSkippedHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();
    $msElement = $eventParams['ms_element'];

    YourAuditLogger::log([
        'event'     => 'webhook_skipped',
        'entity'    => $eventParams['entity'],
        'action'    => $eventParams['action'],
        'href'      => $eventParams['hook']->meta->href,
        'reason'    => $msElement === null ? 'ms_load_failed' : 'not_in_catalog',
        'path_name' => $msElement->pathName ?? '',
        'timestamp' => date('Y-m-d H:i:s'),
    ]);
}