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 in 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 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:

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

Se hai bisogno di supporto per ulteriori argomenti di eventi, contatta l'Assistenza.

txs/new

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

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

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		Indica se il partner è eliminato
from_location		Posizione di origine
from_location.id		ID univoco della posizione di origine
from_location.name		Nome della posizione di origine
from_location.deleted		Indica se la posizione di origine è eliminata
to_location		Posizione di destinazione
to_location.id		ID univoco della posizione di destinazione
to_location.name		Nome della posizione di destinazione
to_location.deleted		Indica se la posizione di destinazione è eliminata
items		Righe articoli della transazione
items.id		ID univoco dell'articolo
items.name		Nome dell'articolo
items.quantity		Variazione di inventario dovuta a entrata/uscita/rettifica/spostamento di stock
items.deleted		Indica se l'articolo è eliminato
items.from_location_new_stock_level		Livello di stock nella posizione di origine dopo la transazione
items.to_location_new_stock_level		Livello di stock nella posizione di destinazione dopo la transazione
transaction_time		Orario della transazione (ad es. orario di entrata/uscita stock)
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		Indica 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 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 – Sposta 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 / Uscita / Rettifica / Spostamento di stock) viene modificata.

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		Indica se il partner è eliminato
from_location		Posizione di origine
from_location.id		ID univoco della posizione di origine
from_location.name		Nome della posizione di origine
from_location.deleted		Indica se la posizione di origine è eliminata
to_location		Posizione di destinazione
to_location.id		ID univoco della posizione di destinazione
to_location.name		Nome della posizione di destinazione
to_location.deleted		Indica se la posizione di destinazione è eliminata
items		Righe articoli della 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		Indica se l'articolo è eliminato
items.from_location_new_stock_level		Livello di stock nella posizione di origine dopo la transazione
items.to_location_new_stock_level		Livello di stock nella posizione di destinazione dopo la transazione
transaction_time		Orario della transazione (ad es. orario di entrata/uscita stock)
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		Indica 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
revision		Numero di versione corrente della transazione, a partire da 1

Esempio di payload webhook – Modificato Entrata 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 – Modificato Sposta 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
revision	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 è non attivato quando si utilizza la funzionalità Aggiungi varianti articolo o quando si importano articoli tramite Importa Excel.

Campo	Descrizione
id	ID articolo
nome	Nome articolo
sku	SKU
scanner	Barcode
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": "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.

Nota: Questo evento è non attivato for modifiche in blocco effettuate tramite Centro dati > Articolo o tramite la Importa Excel funzione.

Campo	Descrizione
id	ID articolo
nome	Nome articolo
sku	SKU
scanner	Barcode
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": "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.

Nota: Questo evento è non attivato per eliminazioni in blocco effettuate tramite Centro dati > Articolo.

Campo	Descrizione
id	ID articolo

Esempio di payload – Articolo eliminato

{
  "id": 26122826
}