Webhook

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

---

Inscription

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

Comportement de livraison et de nouvelle tentative

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

• Si votre serveur répond avec HTTP 200 OK, l’événement est considéré comme livré avec succès.

• Si votre serveur répond avec tout code d’état différent de 200, BoxHero le considère comme un échec temporaire et réessaie la livraison jusqu’à 3 fois.

Structure de la charge utile du webhook

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

{
  "id": "1234", // ID unique de l’événement
  "topic": "txs/new", // Sujet de l’événement
  "version": 1, // Version du schéma de la charge utile
  "payload": { // Données spécifiques à l’événement
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Horodatage du moment où l’événement s’est produit (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.

La fonctionnalité created_time le champ dans la charge utile de l’événement représente l’heure réelle de l’événement. Implémentez une logique idempotente et tolérante à l’ordre dans votre gestionnaire de webhook pour traiter les événements de manière fiable.

Sujets des événements

Si vous avez besoin de prise en charge pour des sujets d’événements supplémentaires, veuillez contacter l’assistance.

txs/new

Déclenché lorsqu’une transaction de stock se produit (Entrée de stock / Sortie de stock / Ajustement de stock / Transfert de stock).

Remarque : Cet événement est ne déclenché pour les ajustements créés via des modifications groupées ou des importations (par exemple, lors de l’ajout ou de la mise à jour d’articles via Excel).

Champ	Obligatoire	Description
id		ID unique de la transaction
type		Type de transaction (in, out, adjust, move)
partenaire		Partenaire
partner.id		ID unique du partenaire
partner.name		Nom du partenaire
partner.deleted		Indique si le partenaire est supprimé
from_location		Emplacement source
from_location.id		ID unique de l’emplacement source
from_location.name		Nom de l’emplacement source
from_location.deleted		Indique si l’emplacement source 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 dans la transaction
items.id		ID unique de l’article
items.name		Nom de l’article
items.quantity		Variation de stock due à une entrée/sortie/ajustement/transfert
items.deleted		Indique si l’article est supprimé
items.from_location_new_stock_level		Niveau de stock à l’emplacement source après la transaction
items.to_location_new_stock_level		Niveau de stock à l’emplacement de destination après la transaction
transaction_time		Heure de la transaction (par ex. heure d’entrée/sortie de stock)
created_at		Heure à laquelle la transaction a été créée
created_by		Membre qui a 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		Quantité totale de variation de stock
url		Adresse URL pour consulter la page de détails de la transaction
memo		Notes liées à la transaction

Exemple de charge utile Webhook – Entrée de stock Événement

{
  "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 Webhook – Déplacer le stock Événement

{
  "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 (Entrée de stock / Sortie de stock / Ajustement de stock / Transfert de stock) est modifiée.

Champ	Obligatoire	Description
id		ID unique de la transaction
type		Type de transaction (in, out, adjust, move)
partenaire		Partenaire
partner.id		ID unique du partenaire
partner.name		Nom du partenaire
partner.deleted		Indique si le partenaire est supprimé
from_location		Emplacement source
from_location.id		ID unique de l’emplacement source
from_location.name		Nom de l’emplacement source
from_location.deleted		Indique si l’emplacement source 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 dans 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 source après la transaction
items.to_location_new_stock_level		Niveau de stock à l’emplacement de destination après la transaction
transaction_time		Heure de la transaction (par ex. heure d’entrée/sortie de stock)
created_at		Heure à laquelle la transaction a été créée
created_by		Membre qui a 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		Quantité totale de variation de stock
url		Adresse URL pour consulter la page de détails de la transaction
memo		Notes liées à la transaction
révision		Numéro de version actuel de la transaction, à partir de 1

Exemple de charge utile Webhook – Modifiée Entrée de stock Transaction

{
  "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 Webhook – Modifiée Déplacer le stock Transaction

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

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

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

Exemple de charge utile Webhook – Transaction supprimée

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

item/new

Envoyé lorsqu’un nouvel article est ajouté à l’inventaire de l’équipe.

Remarque: Cet événement est ne déclenché lors de l’utilisation de la fonctionnalité Ajouter des variantes d’article ou lors de l’importation d’articles via Importer Excel.

Champ	Description
id	ID de l’article
nom	Nom de l’article
sku	SKU
code-barres	Code-barres
photo_url	URL de la photo
coût	Coût
prix	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": "Catégorie",
      "type": "text",
      "value": "Fond de teint"
    },
    {
      "id": 459264,
      "name": "Date d’expiration",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stock de sécurité",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Envoyé lorsqu’un article existant est modifié.

Remarque: Cet événement est ne déclenché pour les modifications groupées effectuées via Centre de données > Article ou via la Importer Excel fonctionnalité.

Champ	Description
id	ID de l’article
nom	Nom de l’article
sku	SKU
code-barres	Code-barres
photo_url	URL de la photo
coût	Coût
prix	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": "Catégorie",
      "type": "text",
      "value": "Fond de teint"
    },
    {
      "id": 459264,
      "name": "Date d’expiration",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stock de sécurité",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

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

Remarque: Cet événement est ne déclenché pour les suppressions groupées effectuées via Centre de données > Article.

Champ	Description
id	ID de l’article

Exemple de charge utile – Article supprimé

{
  "id": 26122826
}