Webhook

I webhook sono funzionalità che ti consentono di ricevere notifiche in tempo reale quando si verificano determinati eventi in BoxHero.

---

Registrazione

Puoi registrare un webhook all'indirizzo Impostazioni > Integrazioni e API 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 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:

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

Se hai bisogno di supporto per ulteriori argomenti evento, contatta Supporto.

txs/new

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

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).

ObbligatorioObbligatorietà

Campo	Obbligatorio	Descrizione
id		ID univoco della transazione
type		Tipo di transazione (in, out, adjust, move)
partner		Partner
partner.id		ID univoco del partner
partner.name		Nome del partner
partner.deleted		Se il partner è eliminato
from_location		Sede di origine
from_location.id		ID univoco della sede di origine
from_location.name		Nome della sede di origine
from_location.deleted		Se la sede di origine è eliminata
to_location		Sede di destinazione
to_location.id		ID univoco della sede di destinazione
to_location.name		Nome della sede di destinazione
to_location.deleted		Se la sede di destinazione è eliminata
items		Voci di riga nella transazione
items.id		ID univoco dell'articolo
items.name		Nome dell'articolo
items.quantity		Variazione di inventario dovuta a entrata/uscita/rettifica/spostamento
items.deleted		Se l'articolo è eliminato
items.from_location_new_stock_level		Livello di scorte nella sede di origine dopo la transazione
items.to_location_new_stock_level		Livello di scorte nella sede di destinazione dopo la transazione
transaction_time		Ora della transazione (ad es. ora di entrata/uscita)
created_at		L'ora in cui la transazione è stata creata
created_by		Membro che ha creato la transazione
created_by.id		ID univoco del membro
created_by.name		Nome del membro
created_by.deleted		Se il membro è eliminato
count_of_items		Numero di articoli
total_quantity		Quantità totale della variazione di inventario
url		Indirizzo URL per visualizzare la pagina dei dettagli della transazione
memo		Note relative alla transazione

Esempio di payload webhook – Entrata di magazzino Evento

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

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

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

ObbligatorioObbligatorietà

Campo	Obbligatorio	Descrizione
id		ID univoco della transazione
type		Tipo di transazione (in, out, adjust, move)
partner		Partner
partner.id		ID univoco del partner
partner.name		Nome del partner
partner.deleted		Se il partner è eliminato
from_location		Sede di origine
from_location.id		ID univoco della sede di origine
from_location.name		Nome della sede di origine
from_location.deleted		Se la sede di origine è eliminata
to_location		Sede di destinazione
to_location.id		ID univoco della sede di destinazione
to_location.name		Nome della sede di destinazione
to_location.deleted		Se la sede di destinazione è eliminata
items		Voci di riga nella transazione
items.id		ID univoco dell'articolo
items.name		Nome dell'articolo
items.quantity		Variazione di quantità dovuta alla transazione (in/out/adjust/move)
items.deleted		Se l'articolo è eliminato
items.from_location_new_stock_level		Livello di scorte nella sede di origine dopo la transazione
items.to_location_new_stock_level		Livello di scorte nella sede di destinazione dopo la transazione
transaction_time		Ora della transazione (ad es. ora di entrata/uscita)
created_at		L'ora in cui la transazione è stata creata
created_by		Membro che ha creato la transazione
created_by.id		ID univoco del membro
created_by.name		Nome del membro
created_by.deleted		Se il membro è eliminato
count_of_items		Numero di articoli
total_quantity		Quantità totale della variazione di inventario
url		Indirizzo URL per visualizzare la pagina dei dettagli della transazione
memo		Note relative alla transazione
revisione		Numero di versione corrente della transazione, a partire da 1

Esempio di payload webhook – Transazione modificata Entrata di magazzino Transazione

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

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

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

item/new

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

Nota: Questo evento viene non attivato quando si utilizza la funzionalità Aggiungi varianti articolo funzione oppure importando articoli tramite Importa Excel.

Obbligatorietà

Campo	Descrizione
id	ID articolo
name	Nome articolo
sku	SKU
barcode	Codice a barre
photo_url	URL foto
cost	Costo
price	Prezzo
attrs	Attributi

Esempio di payload – Articolo creato

{
  "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.

Nota: Questo evento viene non attivato fo per modifiche in blocco effettuate tramite Data Center > Articolo o tramite la Importa Excel funzione.

Obbligatorietà

Campo	Descrizione
id	ID articolo
name	Nome articolo
sku	SKU
barcode	Codice a barre
photo_url	URL foto
cost	Costo
price	Prezzo
attrs	Attributi

Esempio di payload – Articolo aggiornato

{
  "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.

Nota: Questo evento viene non attivato per eliminazioni in blocco effettuate tramite Data Center > Articolo.

Campo	Descrizione
id	ID articolo

Esempio di payload – Articolo eliminato

{
  "id": 26122826
}