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 à Paramètres > Intégrations et API dans votre équipe BoxHero.

Comportement de livraison et de réessai

Lorsqu'un événement se produit, BoxHero envoie une requête HTTP POST à votre point de terminaison de 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 de 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 de la survenue de l'événement (ISO 8601)
}

---

Ordre des événements

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

Le created_time 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 d'événements

Si vous avez besoin d'assistance pour des sujets d'événements supplémentaires, veuillez contacter Assistance.

txs/new

Déclenché lorsqu'une transaction de stock se produit (Entrée de stock / Sortie de stock / Ajuster le stock / Déplacer le stock).

Remarque : Cet événement est pas déclenché pour les ajustements créés via des modifications en masse ou des importations (par ex., lors de l'ajout ou de la mise à jour d'articles via Excel).

ObligatoireObligatoire

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 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/déplacement
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		Le moment où la transaction a été créée
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		Quantité totale de variation de stock
url		Adresse URL pour afficher la page des détails de la transaction
memo		Notes liées à la transaction

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

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Entrepôt 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 du webhook – Déplacer le stock Événement

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Entrepôt 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Entrepôt 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 / Ajuster le stock / Déplacer le stock) est modifiée.

ObligatoireObligatoire

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 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		Le moment où la transaction a été créée
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		Quantité totale de variation de stock
url		Adresse URL pour afficher la page des 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 du webhook – Transaction modifiée Entrée de stock Transaction

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Entrepôt 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 du webhook – Transaction modifiée Déplacer le stock Transaction

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Entrepôt 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Entrepôt 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 du 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 pas déclenché lors de l'utilisation de la Ajouter des variantes d'article fonctionnalité ou lors de l'importation d'articles via Importer Excel.

Obligatoire

Champ	Description
id	ID de l'article
name	Nom de l'article
sku	SKU
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": "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 pas déclenché fou lors de modifications en masse effectuées via Centre de données > Article ou via la Importer Excel fonction.

Obligatoire

Champ	Description
id	ID de l'article
name	Nom de l'article
sku	SKU
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": "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 pas déclenché pour les suppressions en masse effectuées via Centre de données > Article.

Champ	Description
id	ID de l'article

Exemple de charge utile – Article supprimé

{
  "id": 26122826
}