> 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/it/integrazioni/webhook.md).

# Webhook

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

***

## Registrazione

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

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

## 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 recapitato 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 webhook

Tutti gli eventi webhook vengono recapitati 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 di occorrenza dell'evento (ISO 8601)
}
```

***

## Ordine degli eventi

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

Il `created_time` campo nel payload dell'evento rappresenta l'orario effettivo dell'evento. Implementa una logica idempotente e tollerante all'ordine nel tuo gestore webhook per gestire gli eventi in modo affidabile.

## Argomenti evento

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

### `txs/new`

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

{% hint style="warning" %}
**Nota:** Questo evento viene *non* attivato per 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">Obbligatorietà</th><th data-hidden>Descrizione</th><th data-hidden>Modalità team</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID univoco della transazione</td><td>true</td><td>ID univoco della cronologia</td><td>Tutto</td></tr><tr><td>type</td><td>true</td><td>Tipo di transazione<br>(in, out, adjust, move)</td><td>true</td><td><p>Tipo di cronologia.</p><ul><li>Entrata : in</li><li>Uscita : out</li><li>Rettifica : adjust</li><li>Spostamento : move</li></ul></td><td>Tutto</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>Se il partner è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID univoco della sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nome della sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Se la sede di origine è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID univoco della sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nome della sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Se la sede di destinazione è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Voci di riga nella transazione</td><td>true</td><td>Voci per prodotto 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 univoco del prodotto</td><td>Tutte le modalità</td></tr><tr><td>items.name</td><td>true</td><td>Nome dell'articolo</td><td>true</td><td>Nome del prodotto</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</td><td>true</td><td>Quantità di entrata/uscita/rettifica/spostamento di quel prodotto</td><td>Tutte le modalità</td></tr><tr><td>items.deleted</td><td>true</td><td>Se l'articolo è eliminato</td><td>true</td><td>Se il prodotto è eliminato</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Livello di scorte nella sede 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 scorte nella sede di destinazione dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Ora della transazione (ad es. ora di entrata/uscita)</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>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 di magazzino` 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 – `Spostamento 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 di magazzino / Uscita di magazzino / Rettifica scorte / Spostamento scorte) 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">Obbligatorietà</th><th data-hidden>Descrizione</th><th data-hidden>Modalità team</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID univoco della transazione</td><td>true</td><td>ID univoco della cronologia</td><td>Tutto</td></tr><tr><td>type</td><td>true</td><td>Tipo di transazione<br>(in, out, adjust, move)</td><td>true</td><td><p>Tipo di cronologia.</p><ul><li>Entrata : in</li><li>Uscita : out</li><li>Rettifica : adjust</li><li>Spostamento : move</li></ul></td><td>Tutto</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>Se il partner è eliminato</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID univoco della sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nome della sede di origine</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Se la sede di origine è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID univoco della sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nome della sede di destinazione</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Se la sede di destinazione è eliminata</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Voci di riga nella transazione</td><td>true</td><td>Voci per prodotto 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 univoco del prodotto</td><td>Tutte le modalità</td></tr><tr><td>items.name</td><td>true</td><td>Nome dell'articolo</td><td>true</td><td>Nome del prodotto</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>Quantità di entrata/uscita/rettifica/spostamento di quel prodotto</td><td>Tutte le modalità</td></tr><tr><td>items.deleted</td><td>true</td><td>Se l'articolo è eliminato</td><td>true</td><td>Se il prodotto è eliminato</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Livello di scorte nella sede 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 scorte nella sede di destinazione dopo la transazione</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Ora della transazione (ad es. ora di entrata/uscita)</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>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>revisione</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 – Transazione modificata `Entrata di magazzino` 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 – Transazione modificata `Spostamento 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                                  |
| revisione | 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 viene *non* attivato quando si utilizza la <mark style="color:blu;">**`funzionalità Aggiungi varianti articolo`**</mark> funzione oppure importando 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">Obbligatorietà</th><th data-hidden>Descrizione</th><th data-hidden>Modalità team</th></tr></thead><tbody><tr><td>id</td><td>ID articolo</td><td>true</td><td>ID univoco della cronologia</td><td>Tutto</td></tr><tr><td>name</td><td>Nome articolo</td><td>true</td><td><p>Tipo di cronologia.</p><ul><li>Entrata : in</li><li>Uscita : out</li><li>Rettifica : adjust</li><li>Spostamento : move</li></ul></td><td>Tutto</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>Codice a barre</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": "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`

Inviato quando un articolo esistente viene modificato.

{% hint style="warning" %}
**Nota**: Questo evento viene *non* attivato *f*o per modifiche in blocco effettuate tramite <mark style="color:blu;">**`Data Center`**</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">Obbligatorietà</th><th data-hidden>Descrizione</th><th data-hidden>Modalità team</th></tr></thead><tbody><tr><td>id</td><td>ID articolo</td><td>true</td><td>ID univoco della cronologia</td><td>Tutto</td></tr><tr><td>name</td><td>Nome articolo</td><td>true</td><td><p>Tipo di cronologia.</p><ul><li>Entrata : in</li><li>Uscita : out</li><li>Rettifica : adjust</li><li>Spostamento : move</li></ul></td><td>Tutto</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>Codice a barre</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": "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`

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

{% hint style="warning" %}
**Nota**: Questo evento viene *non* attivato per eliminazioni in blocco effettuate tramite <mark style="color:blu;">**`Data Center`**</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">Obbligatorietà</th><th data-hidden>Descrizione</th><th data-hidden>Modalità team</th></tr></thead><tbody><tr><td>id</td><td>ID articolo</td><td>true</td><td>ID univoco della cronologia</td><td>Tutto</td></tr></tbody></table>

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

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