Перейти к содержимому
Руководство пользователя
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

Вебхуки позволяют получать уведомления в реальном времени, когда в BoxHero происходят определённые события.

Регистрация

Заголовок раздела «Регистрация»

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

Доставка и повторные попытки

Заголовок раздела «Доставка и повторные попытки»

При наступлении события BoxHero отправляет HTTP-запрос POST на зарегистрированный адрес вебхука. Тело запроса содержит JSON-данные с описанием события.

  • Если ваш сервер отвечает любым кодом статуса 2xx (например, 200, 201, 204), доставка считается успешной.
  • Любой ответ с кодом, отличным от 2xx, считается ошибкой, и доставка будет повторена.

Структура данных вебхука

Заголовок раздела «Структура данных вебхука»

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

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}

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

Заголовок раздела «Порядок событий»

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

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

Темы событий

Заголовок раздела «Темы событий»

txs/new

Заголовок раздела «txs/new»

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

ПолеОбязательноОписание
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Примечания к транзакции

Пример данных вебхука – событие Stock In

Заголовок раздела «Пример данных вебхука – событие Stock In»
{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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"
}

Пример данных вебхука – событие Move Stock

Заголовок раздела «Пример данных вебхука – событие Move Stock»
{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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

Заголовок раздела «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✓Изменение количества в результате транзакции (приход/расход/корректировка/перемещение)
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

Пример данных вебхука – изменённая транзакция Stock In

Заголовок раздела «Пример данных вебхука – изменённая транзакция Stock In»
{
  "id": 16160911,
  "revision": 2,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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"
}

Пример данных вебхука – изменённая транзакция Move Stock

Заголовок раздела «Пример данных вебхука – изменённая транзакция Move Stock»
{
  "id": 3692714,
  "revision": 2,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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

Заголовок раздела «txs/delete»

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

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

Пример данных вебхука – удалённая транзакция

Заголовок раздела «Пример данных вебхука – удалённая транзакция»
{
  "id": 27036740,
  "revision": 2
}

item/new

Заголовок раздела «item/new»

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

ПолеОписание
idID товара
nameНазвание товара
skuАртикул
barcodeШтрихкод
photo_urlURL фото
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": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Заголовок раздела «item/edit»

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

ПолеОписание
idID товара
nameНазвание товара
skuАртикул
barcodeШтрихкод
photo_urlURL фото
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": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Заголовок раздела «item/delete»

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

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

Пример данных – товар удалён

Заголовок раздела «Пример данных – товар удалён»
{
  "id": 26122826
}