Webhook

Les webhooks sont une fonctionnalité qui vous permet de recevoir des notifications en temps réel lorsque certains événements se produisent dans BoxHero.

Enregistrement

Vous pouvez enregistrer un webhook dans Paramètres > Intégrations et API de votre équipe BoxHero.

Comportement de livraison et de nouvelle tentative

Lorsqu’un événement se produit, BoxHero envoie une requête HTTP POST au point de terminaison de webhook que vous avez enregistré. Le corps de la requête contient une charge utile JSON décrivant l’événement.

Si votre serveur répond avec un code d’état 2xx (p. ex. 200, 201, 204), la livraison est considérée comme réussie.
Toute réponse autre que 2xx est considérée comme un échec et fera l’objet d’une nouvelle tentative.

Structure de la charge utile du webhook

Tous les événements de webhook sont livrés avec la structure JSON suivante dans le corps de la requête :

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}

Ordre des événements

BoxHero ne garantit pas l’ordre de livraison des événements. Par exemple, un événement item/new peut arriver après un événement item/delete pour le même article.

Le champ created_time de la charge utile représente l’heure réelle de l’événement. Mettez en œuvre dans votre gestionnaire de webhook une logique idempotente et tolérante à l’ordre afin de traiter les événements de manière fiable.

Sujets d’événements

txs/new

Déclenché lorsqu’une transaction de stock a lieu (Stockage / Déstockage / Ajuster / Déplacement).

Champ	Obligatoire	Description
id	✓	ID unique de la transaction
type	✓	Type de transaction (in, out, adjust, move)
partner		Partenaire
partner.id		ID unique du partenaire
partner.name		Nom du partenaire
partner.deleted		Indique si le partenaire est supprimé
from_location		Emplacement d’origine
from_location.id		ID unique de l’emplacement d’origine
from_location.name		Nom de l’emplacement d’origine
from_location.deleted		Indique si l’emplacement d’origine est supprimé
to_location	✓	Emplacement de destination
to_location.id	✓	ID unique de l’emplacement de destination
to_location.name	✓	Nom de l’emplacement de destination
to_location.deleted	✓	Indique si l’emplacement de destination est supprimé
items	✓	Lignes d’articles de la transaction
items.id	✓	ID unique de l’article
items.name	✓	Nom de l’article
items.quantity	✓	Variation du stock due au stockage, déstockage, ajustement ou déplacement
items.deleted	✓	Indique si l’article est supprimé
items.from_location_new_stock_level		Niveau de stock à l’emplacement d’origine après la transaction
items.to_location_new_stock_level	✓	Niveau de stock à l’emplacement de destination après la transaction
transaction_time	✓	Date de la transaction (p. ex. date de stockage ou de déstockage)
created_at	✓	Date de création de la transaction
created_by	✓	Membre ayant créé la transaction
created_by.id	✓	ID unique du membre
created_by.name	✓	Nom du membre
created_by.deleted	✓	Indique si le membre est supprimé
count_of_items	✓	Nombre d’articles
total_quantity	✓	Variation totale du stock
url	✓	Adresse URL de la page de détails de la transaction
memo		Notes relatives à la transaction

Exemple de charge utile de webhook – Événement Stock In

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

Exemple de charge utile de webhook – Événement Move Stock

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

Envoyé lorsqu’une transaction de stock existante (Stockage / Déstockage / Déplacement / Ajuster) est modifiée.

Champ	Obligatoire	Description
id	✓	ID unique de la transaction
type	✓	Type de transaction (in, out, adjust, move)
partner		Partenaire
partner.id		ID unique du partenaire
partner.name		Nom du partenaire
partner.deleted		Indique si le partenaire est supprimé
from_location		Emplacement d’origine
from_location.id		ID unique de l’emplacement d’origine
from_location.name		Nom de l’emplacement d’origine
from_location.deleted		Indique si l’emplacement d’origine est supprimé
to_location	✓	Emplacement de destination
to_location.id	✓	ID unique de l’emplacement de destination
to_location.name	✓	Nom de l’emplacement de destination
to_location.deleted	✓	Indique si l’emplacement de destination est supprimé
items	✓	Lignes d’articles de la transaction
items.id	✓	ID unique de l’article
items.name	✓	Nom de l’article
items.quantity	✓	Variation de quantité due à la transaction (in/out/adjust/move)
items.deleted	✓	Indique si l’article est supprimé
items.from_location_new_stock_level		Niveau de stock à l’emplacement d’origine après la transaction
items.to_location_new_stock_level	✓	Niveau de stock à l’emplacement de destination après la transaction
transaction_time	✓	Date de la transaction (p. ex. date de stockage ou de déstockage)
created_at	✓	Date de création de la transaction
created_by	✓	Membre ayant créé la transaction
created_by.id	✓	ID unique du membre
created_by.name	✓	Nom du membre
created_by.deleted	✓	Indique si le membre est supprimé
count_of_items	✓	Nombre d’articles
total_quantity	✓	Variation totale du stock
url	✓	Adresse URL de la page de détails de la transaction
memo		Notes relatives à la transaction
revision	✓	Numéro de version actuel de la transaction, à partir de 1

Exemple de charge utile de webhook – Transaction Stock In modifiée

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

Exemple de charge utile de webhook – Transaction Move Stock modifiée

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

Envoyé lorsqu’une transaction de stock est supprimée.

Champ	Description
id	ID unique de la transaction
revision	Numéro de version actuel de la transaction, à partir de 1

Exemple de charge utile de webhook – Transaction supprimée

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

item/new

Envoyé lorsqu’un nouvel article est ajouté au stock de l’équipe.

Champ	Description
id	ID de l’article
name	Nom de l’article
sku	UGS
barcode	Code-barres
photo_url	URL de la photo
cost	Coût
price	Prix
attrs	Attributs

Exemple de charge utile – Article créé

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

Envoyé lorsqu’un article existant est modifié.

Champ	Description
id	ID de l’article
name	Nom de l’article
sku	UGS
barcode	Code-barres
photo_url	URL de la photo
cost	Coût
price	Prix
attrs	Attributs

Exemple de charge utile – Article mis à jour

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

Envoyé lorsqu’un article est supprimé du stock de l’équipe.

Champ	Description
id	ID de l’article

Exemple de charge utile – Article supprimé

{
  "id": 26122826
}