> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.boxhero.io/docs/documentation/ru/integracii/webhook.md).

# Вебхук

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

<figure><img src="https://740025866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2FY1xAFhph1Gpp4FxnSZ7I%2F05_API.jpg?alt=media&amp;token=500a0d78-d0b9-4c05-a3ee-02f1d7d91039" alt=""><figcaption></figcaption></figure>

***

## Регистрация

Вы можете зарегистрировать вебхук в <mark style="color:$primary;">`Настройки`</mark> > <mark style="color:$primary;">`Интеграции`</mark> в вашей команде BoxHero.

<figure><img src="https://740025866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2Fgit-blob-094f1326e4f5b66d3f4de825a63e55cbf0f4ac01%2Fboxhero-add-webhook.png?alt=media" alt=""><figcaption></figcaption></figure>

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

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

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

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

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

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

***

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

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

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

## Темы событий

{% hint style="info" %}
Если вам нужна поддержка дополнительных тем событий, пожалуйста, свяжитесь с [Поддержкой](/docs/documentation/ru/resursy/contact.md).
{% endhint %}

### `txs/new`

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

{% hint style="warning" %}
**Примечание:** Это событие *не* срабатывает для корректировок, созданных через массовое редактирование или импорт (например, при добавлении или обновлении товаров через Excel).
{% endhint %}

<table><thead><tr><th width="207">Поле</th><th width="100" data-type="checkbox">Обязательное</th><th>Описание</th><th data-hidden data-type="checkbox">Обязательность</th><th data-hidden>Описание</th><th data-hidden>Режим команды</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>Уникальный ID транзакции</td><td>true</td><td>Уникальный ID истории</td><td>Все</td></tr><tr><td>type</td><td>true</td><td>Тип транзакции<br>(поступление, списание, корректировка, перемещение)</td><td>true</td><td><p>Тип истории.</p><ul><li>Поступление : in</li><li>Списание : out</li><li>Корректировка : adjust</li><li>Перемещение : move</li></ul></td><td>Все</td></tr><tr><td>partner</td><td>false</td><td>Партнёр</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>Уникальный ID партнёра</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Имя партнёра</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Удалён ли партнёр</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Исходная локация</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>Уникальный ID исходной локации</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Имя исходной локации</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Удалена ли исходная локация</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Целевая локация</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>Уникальный ID целевой локации</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Имя целевой локации</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Удалена ли целевая локация</td><td>false</td><td></td><td></td></tr><tr><td>товары</td><td>true</td><td>Позиции в транзакции</td><td>true</td><td>Позиции по товарам, составляющие историю</td><td>Все режимы</td></tr><tr><td>items.id</td><td>true</td><td>Уникальный ID товара</td><td>true</td><td>Уникальный ID товара</td><td>Все режимы</td></tr><tr><td>items.name</td><td>true</td><td>Название товара</td><td>true</td><td>Название товара</td><td>Все режимы</td></tr><tr><td>items.quantity</td><td>true</td><td>Изменение запасов из-за поступления/списания/корректировки/перемещения</td><td>true</td><td>Количество поступления/списания/корректировки/перемещения для данного товара</td><td>Все режимы</td></tr><tr><td>items.deleted</td><td>true</td><td>Удалён ли товар</td><td>true</td><td>Удалён ли товар</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Уровень запасов на исходной локации после транзакции</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Уровень запасов на целевой локации после транзакции</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Время транзакции (например, время поступления/списания)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Время, когда транзакция была создана</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Участник, создавший транзакцию</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>Уникальный ID участника</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Имя участника</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Удалён ли участник</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Количество товаров</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Общее количество изменения запасов</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>URL-адрес для просмотра страницы с деталями транзакции</td><td>false</td><td></td><td></td></tr><tr><td>примечании</td><td>false</td><td>Примечания, связанные с транзакцией</td><td>false</td><td></td><td></td></tr></tbody></table>

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

```json
{
  "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"
}
```

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

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Склад 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Склад 3",
<strong>    "deleted": false
</strong>  },
  "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"
}
</code></pre>

### `txs/edit`

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

<table><thead><tr><th>Поле</th><th width="100" data-type="checkbox">Обязательное</th><th>Описание</th><th data-hidden data-type="checkbox">Обязательность</th><th data-hidden>Описание</th><th data-hidden>Режим команды</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>Уникальный ID транзакции</td><td>true</td><td>Уникальный ID истории</td><td>Все</td></tr><tr><td>type</td><td>true</td><td>Тип транзакции<br>(поступление, списание, корректировка, перемещение)</td><td>true</td><td><p>Тип истории.</p><ul><li>Поступление : in</li><li>Списание : out</li><li>Корректировка : adjust</li><li>Перемещение : move</li></ul></td><td>Все</td></tr><tr><td>partner</td><td>false</td><td>Партнёр</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>Уникальный ID партнёра</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Имя партнёра</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Удалён ли партнёр</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Исходная локация</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>Уникальный ID исходной локации</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Имя исходной локации</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Удалена ли исходная локация</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Целевая локация</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>Уникальный ID целевой локации</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Имя целевой локации</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Удалена ли целевая локация</td><td>false</td><td></td><td></td></tr><tr><td>товары</td><td>true</td><td>Позиции в транзакции</td><td>true</td><td>Позиции по товарам, составляющие историю</td><td>Все режимы</td></tr><tr><td>items.id</td><td>true</td><td>Уникальный ID товара</td><td>true</td><td>Уникальный ID товара</td><td>Все режимы</td></tr><tr><td>items.name</td><td>true</td><td>Название товара</td><td>true</td><td>Название товара</td><td>Все режимы</td></tr><tr><td>items.quantity</td><td>true</td><td>Изменение количества из-за транзакции (поступление/списание/корректировка/перемещение)</td><td>true</td><td>Количество поступления/списания/корректировки/перемещения для данного товара</td><td>Все режимы</td></tr><tr><td>items.deleted</td><td>true</td><td>Удалён ли товар</td><td>true</td><td>Удалён ли товар</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Уровень запасов на исходной локации после транзакции</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Уровень запасов на целевой локации после транзакции</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Время транзакции (например, время поступления/списания)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Время, когда транзакция была создана</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Участник, создавший транзакцию</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>Уникальный ID участника</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Имя участника</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Удалён ли участник</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Количество товаров</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Общее количество изменения запасов</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>URL-адрес для просмотра страницы с деталями транзакции</td><td>false</td><td></td><td></td></tr><tr><td>примечании</td><td>false</td><td>Примечания, связанные с транзакцией</td><td>false</td><td></td><td></td></tr><tr><td>revision</td><td>true</td><td>Текущий номер версии транзакции, начиная с 1</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Пример полезной нагрузки вебхука – отредактировано `Приход` Операция

```json
{
  "id": 16160911,
  "revision": 2,
  "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"
}

```

#### Пример полезной нагрузки вебхука – отредактировано `Перемещение` Операция

```json
{
  "id": 3692714,
  "revision": 2,
  "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 |

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

```json
{
  "id": 27036740,
  "revision": 2
}
```

### `item/new`

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

{% hint style="warning" %}
**Примечание**: Это событие *не* срабатывает при использовании <mark style="color:$primary;">`функции Add Item Variants`</mark> или при импорте товаров через <mark style="color:$primary;">`Импорт из Excel`</mark>.
{% endhint %}

<table><thead><tr><th width="318">Поле</th><th>Описание</th><th data-hidden data-type="checkbox">Обязательность</th><th data-hidden>Описание</th><th data-hidden>Режим команды</th></tr></thead><tbody><tr><td>id</td><td>ID товара</td><td>true</td><td>Уникальный ID истории</td><td>Все</td></tr><tr><td>названию</td><td>Название товара</td><td>true</td><td><p>Тип истории.</p><ul><li>Поступление : in</li><li>Списание : out</li><li>Корректировка : adjust</li><li>Перемещение : move</li></ul></td><td>Все</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>штрихкоде</td><td>Штрихкод</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL фотографии</td><td>false</td><td></td><td></td></tr><tr><td>стоимость</td><td>Стоимость</td><td>false</td><td></td><td></td></tr><tr><td>цена</td><td>Цена</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Атрибуты</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Пример payload — созданный товар**

```json
{
  "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`

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

{% hint style="warning" %}
**Примечание**: Это событие *не* срабатывает для массовых изменений, выполненных через <mark style="color:$primary;">`Центр данных`</mark> > <mark style="color:$primary;">`Item`</mark> или через <mark style="color:$primary;">`Импорт из Excel`</mark> функцию.
{% endhint %}

<table><thead><tr><th width="318">Поле</th><th>Описание</th><th data-hidden data-type="checkbox">Обязательность</th><th data-hidden>Описание</th><th data-hidden>Режим команды</th></tr></thead><tbody><tr><td>id</td><td>ID товара</td><td>true</td><td>Уникальный ID истории</td><td>Все</td></tr><tr><td>названию</td><td>Название товара</td><td>true</td><td><p>Тип истории.</p><ul><li>Поступление : in</li><li>Списание : out</li><li>Корректировка : adjust</li><li>Перемещение : move</li></ul></td><td>Все</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>штрихкоде</td><td>Штрихкод</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL фотографии</td><td>false</td><td></td><td></td></tr><tr><td>стоимость</td><td>Стоимость</td><td>false</td><td></td><td></td></tr><tr><td>цена</td><td>Цена</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Атрибуты</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Пример payload — обновлённый товар**

```json
{
  "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`

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

{% hint style="warning" %}
**Примечание**: Это событие *не* срабатывает для массовых удалений, выполненных через <mark style="color:$primary;">`Центр данных`</mark> > <mark style="color:$primary;">`Товары`</mark>.
{% endhint %}

<table><thead><tr><th width="318">Поле</th><th>Описание</th><th data-hidden data-type="checkbox">Обязательность</th><th data-hidden>Описание</th><th data-hidden>Режим команды</th></tr></thead><tbody><tr><td>id</td><td>ID товара</td><td>true</td><td>Уникальный ID истории</td><td>Все</td></tr></tbody></table>

#### Пример payload **— удалённый товар**

```json
{
  "id": 26122826
}
```