Callback.API

Callback информируют сторонние системы о создании, изменении или удалении данных в Brandquad. Объектами для срабатывания триггера отправки сallback-запроса служат товары, списки товаров и сертификаты.

При этом учитываются все варианты выполнения действий с перечисленными объектами – в каталоге и карточке товара, посредством API (v1, v2, v3), с помощью массовых операций, импорта данных и т.д.

1 Что нужно учитывать при настройке callback
2 Как добавить вебхук
3 Как отследить логи исполненных callback-запросов
4 Как удалить вебхуки

Что нужно учитывать при настройке callback

Принципы работы

Когда наступает одно из событий, Brandquad выбирает подходящие подписки и рассылает сообщения сторонним системам. Если подходящих подписок несколько, то события отправляются параллельно на все адреса.

Callback атомарны, это означает, что всегда происходит 1 запрос для 1 объекта. Например, в качестве действия была выбрана массовая операция по удалению 25 товаров, то будет создано 25 callback запросов и 25 записей в лог.

Все запросы по callback происходят в фоновых задачах. Для отслеживаемых действий "удаление товара" и "создание товара" задачи ставятся на исполнение сразу.

Для отслеживаемого действия “изменение товара” задачи выполняются с задержкой в 60 секунд. При накопительном изменении товара в течение 1 минуты выполняется только 1 запрос. Алгоритм выполнения следующий:

В кэше по ключу {ACCOUNT_ID}-hook-update-sku-set создается структура типа set, в которой помещается SKU изменяемого товара. При любом изменении происходит проверка наличия SKU в этом списке. Если SKU уже находится в списке, то он пропускается.
После добавления нового SKU в список создается задача с отложенным исполнением (60 сек).
В момент запуска отложенной задачи из кэша удаляется SKU, по которому происходит callback.

Очередь отправки

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

Формат запросов

Все запросы по вебхукам происходят методом POST. В payload запроса отправляется JSON формат. Параметр "action" может иметь следующие значения: 0 – create, 1 – update, 2 – delete.

Как добавить вебхук

На сайте Webhook.site - Test, process and transform emails and HTTP requests сгенерируйте вебхук и скопируйте его.

Далее в панели администрирования платформы Brandquad откройте раздел Callbacks Api” → “Callbacks и нажмите “Добавить Callbacks”. Заполните и сохраните параметры нового вебхука:

Name – наименование Callback.
URL – скопированный адрес, на который будет отправлено событие (требуется указывать протокол).
Entry – тип объекта, действие с которым запускает вебхук (продукт, список товаров и сертификат).
Action – тип действия, после которого будет отправляться запрос в стороннюю систему.
Headers – заголовки запроса, которые будут передаваться в стороннюю систему.
Account – аккаунт, отслеживаемые действия на котором будут генерировать события.
Таймаут в секундах – таймаут отправки запроса.

Как отследить логи исполненных callback-запросов

Все исполненные callback логируются и хранятся в модуле администрирования платформы “Callbacks Api” → “Callbacks Requests History”.

Каждая запись содержит данные с детализацией до уровня status + item ID + action + created + account + callback.

Обратите внимание:

При изменении триггерного действия в поле Action параметров коллбэка (раздел “Callbacks Api” → “Callbacks”) запись лога останется неизменной.

Запись лога успешно обработанного запроса имеет статус 200. Другие статусы (например, 204, 404 и.т.д.) говорят о том, что при обработке запроса возникли какие-либо проблемы.

На сайте Webhook.site - Test, process and transform emails and HTTP requests при обработке новой сущности (например, создании сертификата, удалении списка товара и.т.д.) будет сформирован POST-запрос.

Примеры логирования:

В разделе “Callbacks Api” → “Callbacks” админ-панели Brandquad создан вебхук для отправки запросов при добавлении сертификатов.

Предположим, в аккаунте создан новый сертификат с ID 670. Это событие отобразится в разделе “Callbacks Api” → “Callbacks Requests History” одной записью:

Статус записи 404 говорит о том, что запрос обработан с ошибкой.

В разделе “Callbacks Api” → “Callbacks” админ-панели Brandquad создан вебхук для отправки запросов при обновлении списков товаров:

Предположим, в один из списков с ID 91 были добавлены новые товары. После этого в разделе “Callbacks Api” → “Callbacks Requests History” будет создана одна запись:

Статус записи 200 говорит о том, что запрос обработан успешно.

В разделе “Callbacks Api” → “Callbacks” админ-панели Brandquad создан вебхук для отправки запросов при удалении товаров.

Предположим, с помощью массовой операции из каталога товаров было удалено два товара с SKU 454789 и 365548. После этого в разделе “Callbacks Api” → “Callbacks Requests History” будут созданы две записи на каждый товар:

Статус запись 204 говорит об успешной обработке запроса, но частичной передаче данных.

Как удалить вебхуки

Вебхуки удаляются вместе с записями о срабатывании в истории логов. Перед удалением рекомендуем проверить данные в разделе “Callbacks Api” → “Callbacks Requests History”, выполнив фильтрацию записей по вебхуку.

Если по вебхуку не было ни одного срабатывания, то его можно удалить. Для этого в разделе “Callbacks Api” → “Callbacks” отметьте вебхуки галочками, выберите “Удалить выбранные Callbacks” в меню “Действия” и нажмите “Выполнить”.

На открывшейся странице ознакомьтесь со списком удаляемых объектов и подтвердите выполнение действия.