Вебхук

Вебхуки — это функции, которые позволяют получать уведомления в реальном времени при наступлении определенных событий в BoxHero.

---

Регистрация

Вы можете зарегистрировать вебхук по адресу Настройки > Интеграции и API в вашей команде BoxHero.

Поведение доставки и повторных попыток

Когда происходит событие, BoxHero отправляет HTTP POST запрос на вашу зарегистрированную конечную точку вебхука. Тело запроса содержит JSON-полезную нагрузку, описывающую событие.

• Если ваш сервер отвечает HTTP 200 OK, событие считается успешно доставленным.

• Если ваш сервер отвечает любой статус-код, отличный от 200, BoxHero считает это временной ошибкой и повторяет доставку до 3 раз.

Структура полезной нагрузки вебхука

Все события вебхука передаются в теле запроса со следующей JSON-структурой:

{
  "id": "1234", // Уникальный ID события
  "topic": "txs/new", // Тема события
  "version": 1, // Версия схемы полезной нагрузки
  "payload": { // Данные, специфичные для события
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Временная метка наступления события (ISO 8601)
}

---

Порядок событий

BoxHero не гарантирует порядок доставки событий. Например, событие item/new может прийти после события item/delete для того же товара.

Поле created_time в полезной нагрузке события представляет фактическое время события. Реализуйте идемпотентную и устойчивую к порядку логику в обработчике вебхука, чтобы надежно обрабатывать события.

Темы событий

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

txs/new

Срабатывает при выполнении складской операции (приход / расход / корректировка / перемещение).

Примечание: Это событие не срабатывает для корректировок, созданных через массовое редактирование или импорт (например, при добавлении или обновлении товаров через Excel).

Поле	Обязательно	Описание
id		Уникальный ID транзакции
type		Тип транзакции (in, out, adjust, move)
partner		Партнёр
partner.id		Уникальный ID партнёра
partner.name		Имя партнёра
partner.deleted		Удалён ли партнёр
from_location		Исходное местоположение
from_location.id		Уникальный ID исходного местоположения
from_location.name		Название исходного местоположения
from_location.deleted		Удалено ли исходное местоположение
to_location		Место назначения
to_location.id		Уникальный ID места назначения
to_location.name		Название места назначения
to_location.deleted		Удалено ли место назначения
items		Позиции транзакции
items.id		Уникальный ID товара
items.name		Название товара
items.quantity		Изменение запасов из-за прихода/расхода/корректировки/перемещения
items.deleted		Удалён ли товар
items.from_location_new_stock_level		Остаток на исходном месте после транзакции
items.to_location_new_stock_level		Остаток в месте назначения после транзакции
transaction_time		Время транзакции (например, время прихода/расхода)
created_at		Время создания транзакции
created_by		Участник, создавший транзакцию
created_by.id		Уникальный ID участника
created_by.name		Имя участника
created_by.deleted		Удалён ли участник
count_of_items		Количество товаров
total_quantity		Общее количество изменения запасов
url		URL-адрес для просмотра страницы деталей транзакции
memo		Примечания, связанные с транзакцией

Пример полезной нагрузки вебхука — Приход Событие

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Склад 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Пример полезной нагрузки вебхука — Перемещение запасов Событие

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Склад 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Склад 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2025-04-25T05:42:27.545Z",
  "created_at": "2025-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Tony Lee",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/edit

Отправляется, когда существующая складская операция (приход / расход / корректировка / перемещение) изменена.

Поле	Обязательно	Описание
id		Уникальный ID транзакции
type		Тип транзакции (in, out, adjust, move)
partner		Партнёр
partner.id		Уникальный ID партнёра
partner.name		Имя партнёра
partner.deleted		Удалён ли партнёр
from_location		Исходное местоположение
from_location.id		Уникальный ID исходного местоположения
from_location.name		Название исходного местоположения
from_location.deleted		Удалено ли исходное местоположение
to_location		Место назначения
to_location.id		Уникальный ID места назначения
to_location.name		Название места назначения
to_location.deleted		Удалено ли место назначения
items		Позиции транзакции
items.id		Уникальный ID товара
items.name		Название товара
items.quantity		Изменение количества из-за транзакции (in/out/adjust/move)
items.deleted		Удалён ли товар
items.from_location_new_stock_level		Остаток на исходном месте после транзакции
items.to_location_new_stock_level		Остаток в месте назначения после транзакции
transaction_time		Время транзакции (например, время прихода/расхода)
created_at		Время создания транзакции
created_by		Участник, создавший транзакцию
created_by.id		Уникальный ID участника
created_by.name		Имя участника
created_by.deleted		Удалён ли участник
count_of_items		Количество товаров
total_quantity		Общее количество изменения запасов
url		URL-адрес для просмотра страницы деталей транзакции
memo		Примечания, связанные с транзакцией
revision		Текущий номер версии транзакции, начиная с 1

Пример полезной нагрузки вебхука — Изменённая транзакция Приход Транзакция

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Склад 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Пример полезной нагрузки вебхука — Изменённая транзакция Перемещение запасов Транзакция

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Склад 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Склад 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/delete

Отправляется, когда складская операция удалена.

Поле	Описание
id	Уникальный ID транзакции
revision	Текущий номер версии транзакции, начиная с 1

Пример полезной нагрузки вебхука — Удалённая транзакция

/{
  "id": 27036740,
  "revision": 2
}

item/new

Отправляется, когда новый товар добавляется на склад команды.

Примечание: Это событие не срабатывает при использовании Добавление вариантов товара функции или при импорте товаров через Импорт Excel.

Поле	Описание
id	ID товара
name	Название товара
sku	SKU
barcode	Штрихкод
photo_url	URL фотографии
cost	Себестоимость
price	Цена
attrs	Атрибуты

Пример полезной нагрузки — Товар создан

{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Категория",
      "type": "text",
      "value": "Тональная основа"
    },
    {
      "id": 459264,
      "name": "Срок годности",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Страховой запас",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Отправляется, когда существующий товар изменён.

Примечание: Это событие не срабатывает fили при массовом редактировании через Центр данных > Товар или через Импорт Excel функцию.

Поле	Описание
id	ID товара
name	Название товара
sku	SKU
barcode	Штрихкод
photo_url	URL фотографии
cost	Себестоимость
price	Цена
attrs	Атрибуты

Пример полезной нагрузки — Товар обновлён

{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Категория",
      "type": "text",
      "value": "Тональная основа"
    },
    {
      "id": 459264,
      "name": "Срок годности",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Страховой запас",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Отправляется, когда товар удаляется из запасов команды.

Примечание: Это событие не срабатывает при массовом удалении через Центр данных > Товар.

Поле	Описание
id	ID товара

Пример полезной нагрузки — Товар удалён

{
  "id": 26122826
}