# Webhook

<figure><img src="/files/a2e99f1d4467051fb7f03ff96bda1bb40b9ec044" alt=""><figcaption></figcaption></figure>

***

## Registrazione

Puoi registrare un webhook in <mark style="color:blu;">**`Impostazioni`**</mark> **>** <mark style="color:blu;">**`Integrazioni e API`**</mark> nel tuo team BoxHero.

## Comportamento di consegna e ritentativo

Quando si verifica un evento, BoxHero invia una richiesta HTTP `POST` al tuo endpoint webhook registrato. Il corpo della richiesta contiene un payload JSON che descrive l'evento.

* Se il tuo server risponde con **HTTP 200 OK**, l'evento è considerato consegnato con successo.
* Se il tuo server risponde con **qualsiasi codice di stato diverso da 200**, BoxHero lo considera un errore temporaneo e ritenta la consegna fino a 3 volte.

## Struttura del payload del webhook

Tutti gli eventi webhook vengono consegnati con la seguente struttura JSON nel corpo della richiesta:

```json
{
  "id": "1234", // ID univoco dell'evento
  "topic": "txs/new", // Argomento dell'evento
  "version": 1, // Versione dello schema del payload
  "payload": { // Dati specifici dell'evento
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp del verificarsi dell'evento (ISO 8601)
}
```

***

## Ordine degli eventi

BoxHero **non** garantisce l'ordine di consegna degli eventi. Ad esempio, un evento `item/new` può arrivare dopo un evento `item/delete` per lo stesso articolo.

La `created_time` il campo nel payload dell'evento rappresenta l'ora effettiva dell'evento. Implementa una logica idempotente e tollerante all'ordine nel tuo gestore webhook per elaborare gli eventi in modo affidabile.

## Argomenti degli eventi

{% hint style="info" %}
Se hai bisogno di supporto per ulteriori argomenti di eventi, contatta [l'Assistenza](/docs/documentation/it/risorse/contact.md).
{% endhint %}

### `txs/new`

Attivato quando si verifica una transazione di inventario (Entrata / Uscita / Rettifica / Spostamento di stock).

{% hint style="warning" %}
**Nota:** Questo evento è *non* attivato per le rettifiche create tramite modifiche in blocco o importazioni (ad es. quando si aggiungono o aggiornano articoli tramite Excel).
{% endhint %}

<table><thead><tr><th width="207">Campo</th><th width="100" data-type="checkbox">Obbligatorio</th><th>Descrizione</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 univoco della transazione</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>Tipo di transazione<br>(in, out, adjust, move)</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>Partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID univoco del partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nome del partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Indica se il partner è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID univoco della posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nome della posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Indica se la posizione di origine è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID univoco della posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nome della posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Indica se la posizione di destinazione è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Righe articoli della transazione</td><td>true</td><td>제품별 항목 che compongono la cronologia</td><td>Tutte le modalità</td></tr><tr><td>items.id</td><td>true</td><td>ID univoco dell'articolo</td><td>true</td><td>제품의 고유 ID</td><td>Tutte le modalità</td></tr><tr><td>items.name</td><td>true</td><td>Nome dell'articolo</td><td>true</td><td>제품의 이름</td><td>Tutte le modalità</td></tr><tr><td>items.quantity</td><td>true</td><td>Variazione di inventario dovuta a entrata/uscita/rettifica/spostamento di stock</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>Tutte le modalità</td></tr><tr><td>items.deleted</td><td>true</td><td>Indica se l'articolo è eliminato</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Livello di stock nella posizione di origine dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Livello di stock nella posizione di destinazione dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Orario della transazione (ad es. orario di entrata/uscita stock)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>L'ora in cui la transazione è stata creata</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Membro che ha creato la transazione</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID univoco del membro</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nome del membro</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Indica se il membro è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Numero di articoli</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Quantità totale della variazione di inventario</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Indirizzo URL per visualizzare la pagina dei dettagli della transazione</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Note relative alla transazione</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Esempio di payload webhook – `Entrata` Evento

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

#### Esempio di payload webhook – `Sposta scorte` Evento

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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`

Inviato quando una transazione di inventario esistente (Entrata / Uscita / Rettifica / Spostamento di stock) viene **modificata**.

<table><thead><tr><th>Campo</th><th width="100" data-type="checkbox">Obbligatorio</th><th>Descrizione</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 univoco della transazione</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>Tipo di transazione<br>(in, out, adjust, move)</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>Partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID univoco del partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nome del partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Indica se il partner è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID univoco della posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nome della posizione di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Indica se la posizione di origine è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID univoco della posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nome della posizione di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Indica se la posizione di destinazione è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Righe articoli della transazione</td><td>true</td><td>제품별 항목 che compongono la cronologia</td><td>Tutte le modalità</td></tr><tr><td>items.id</td><td>true</td><td>ID univoco dell'articolo</td><td>true</td><td>제품의 고유 ID</td><td>Tutte le modalità</td></tr><tr><td>items.name</td><td>true</td><td>Nome dell'articolo</td><td>true</td><td>제품의 이름</td><td>Tutte le modalità</td></tr><tr><td>items.quantity</td><td>true</td><td>Variazione di quantità dovuta alla transazione (in/out/adjust/move)</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>Tutte le modalità</td></tr><tr><td>items.deleted</td><td>true</td><td>Indica se l'articolo è eliminato</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Livello di stock nella posizione di origine dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Livello di stock nella posizione di destinazione dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Orario della transazione (ad es. orario di entrata/uscita stock)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>L'ora in cui la transazione è stata creata</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Membro che ha creato la transazione</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID univoco del membro</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nome del membro</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Indica se il membro è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Numero di articoli</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Quantità totale della variazione di inventario</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Indirizzo URL per visualizzare la pagina dei dettagli della transazione</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Note relative alla transazione</td><td>false</td><td></td><td></td></tr><tr><td>revision</td><td>true</td><td>Numero di versione corrente della transazione, a partire da 1</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Esempio di payload webhook – Modificato `Entrata` Transazione

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

```

#### Esempio di payload webhook – Modificato `Sposta scorte` Transazione

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

Inviato quando una transazione di inventario viene **eliminata**.

| Campo    | Descrizione                                                   |
| -------- | ------------------------------------------------------------- |
| id       | ID univoco della transazione                                  |
| revision | Numero di versione corrente della transazione, a partire da 1 |

#### Esempio di payload webhook – Transazione eliminata

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

### `item/new`

Inviato quando un nuovo articolo viene aggiunto all'inventario del team.

{% hint style="warning" %}
**Nota**: Questo evento è *non* attivato quando si utilizza la funzionalità <mark style="color:blu;">**`Aggiungi varianti articolo`**</mark> o quando si importano articoli tramite <mark style="color:blu;">**`Importa Excel`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Campo</th><th>Descrizione</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 articolo</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>nome</td><td>Nome articolo</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>scanner</td><td>Barcode</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL foto</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Costo</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Prezzo</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributi</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Esempio di payload – Articolo creato**

```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": "Categoria",
      "type": "text",
      "value": "Fondotinta"
    },
    {
      "id": 459264,
      "name": "Data di scadenza",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Scorta di sicurezza",
      "type": "number",
      "value": 33
    }
  ]
}
```

### `item/edit`

Inviato quando un articolo esistente viene modificato.

{% hint style="warning" %}
**Nota**: Questo evento è *non* attivato *f*or modifiche in blocco effettuate tramite <mark style="color:blu;">**`Centro dati`**</mark>**&#x20;>&#x20;**<mark style="color:blu;">**`Articolo`**</mark> o tramite la <mark style="color:blu;">**`Importa Excel`**</mark> funzione.
{% endhint %}

<table><thead><tr><th width="318">Campo</th><th>Descrizione</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 articolo</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>nome</td><td>Nome articolo</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>scanner</td><td>Barcode</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL foto</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Costo</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Prezzo</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributi</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Esempio di payload – Articolo aggiornato**

```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": "Categoria",
      "type": "text",
      "value": "Fondotinta"
    },
    {
      "id": 459264,
      "name": "Data di scadenza",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Scorta di sicurezza",
      "type": "number",
      "value": 33
    }
  ]
}
```

### `item/delete`

Inviato quando un articolo viene eliminato dall'inventario del team.

{% hint style="warning" %}
**Nota**: Questo evento è *non* attivato per eliminazioni in blocco effettuate tramite <mark style="color:blu;">**`Centro dati`**</mark>**&#x20;>&#x20;**<mark style="color:blu;">**`Articolo`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Campo</th><th>Descrizione</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 articolo</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr></tbody></table>

#### Esempio di payload **– Articolo eliminato**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/it/integrazioni/open-api/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.