# Webhook

<figure><img src="https://3800759416-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2Fgit-blob-094f1326e4f5b66d3f4de825a63e55cbf0f4ac01%2Fboxhero-add-webhook.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Inscription

Vous pouvez enregistrer un webhook dans <mark style="color:bleue;">**`Paramètres`**</mark> **>** <mark style="color:bleue;">**`Intégrations et API`**</mark> 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 :

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

{% hint style="info" %}
Si vous avez besoin de prise en charge pour des sujets d’événements supplémentaires, veuillez contacter [l’assistance](https://www.boxhero.io/docs/documentation/fr/ressources/contact).
{% endhint %}

### `txs/new`

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

{% hint style="warning" %}
**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).
{% endhint %}

<table><thead><tr><th width="207">Champ</th><th width="100" data-type="checkbox">Obligatoire</th><th>Description</th><th data-hidden data-type="checkbox">Obligation</th><th data-hidden>Description</th><th data-hidden>Mode équipe</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID unique de la transaction</td><td>true</td><td>ID unique de l’historique</td><td>Tous</td></tr><tr><td>type</td><td>true</td><td>Type de transaction<br>(in, out, adjust, move)</td><td>true</td><td><p>Type de l’historique.</p><ul><li>Entrée : in</li><li>Sortie : out</li><li>Ajustement : adjust</li><li>Transfert : move</li></ul></td><td>Tous</td></tr><tr><td>partenaire</td><td>false</td><td>Partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID unique du partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nom du partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Indique si le partenaire est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID unique de l’emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nom de l’emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Indique si l’emplacement source est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID unique de l’emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nom de l’emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Indique si l’emplacement de destination est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Lignes d’articles dans la transaction</td><td>true</td><td>Articles par produit composant l’historique</td><td>Tous les modes</td></tr><tr><td>items.id</td><td>true</td><td>ID unique de l’article</td><td>true</td><td>ID unique du produit</td><td>Tous les modes</td></tr><tr><td>items.name</td><td>true</td><td>Nom de l’article</td><td>true</td><td>Nom du produit</td><td>Tous les modes</td></tr><tr><td>items.quantity</td><td>true</td><td>Variation de stock due à une entrée/sortie/ajustement/transfert</td><td>true</td><td>Quantité d’entrée/sortie/ajustement/transfert pour ce produit</td><td>Tous les modes</td></tr><tr><td>items.deleted</td><td>true</td><td>Indique si l’article est supprimé</td><td>true</td><td>Indique si le produit est supprimé</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Niveau de stock à l’emplacement source après la transaction</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Niveau de stock à l’emplacement de destination après la transaction</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Heure de la transaction (par ex. heure d’entrée/sortie de stock)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Heure à laquelle la transaction a été créée</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Membre qui a créé la transaction</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID unique du membre</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nom du membre</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Indique si le membre est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Nombre d’articles</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Quantité totale de variation de stock</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Adresse URL pour consulter la page de détails de la transaction</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Notes liées à la transaction</td><td>false</td><td></td><td></td></tr></tbody></table>

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

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

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
<strong>    "deleted": false
</strong>  },
  "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"
}
</code></pre>

### `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**.

<table><thead><tr><th>Champ</th><th width="100" data-type="checkbox">Obligatoire</th><th>Description</th><th data-hidden data-type="checkbox">Obligation</th><th data-hidden>Description</th><th data-hidden>Mode équipe</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID unique de la transaction</td><td>true</td><td>ID unique de l’historique</td><td>Tous</td></tr><tr><td>type</td><td>true</td><td>Type de transaction<br>(in, out, adjust, move)</td><td>true</td><td><p>Type de l’historique.</p><ul><li>Entrée : in</li><li>Sortie : out</li><li>Ajustement : adjust</li><li>Transfert : move</li></ul></td><td>Tous</td></tr><tr><td>partenaire</td><td>false</td><td>Partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID unique du partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nom du partenaire</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Indique si le partenaire est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID unique de l’emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nom de l’emplacement source</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Indique si l’emplacement source est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID unique de l’emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nom de l’emplacement de destination</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Indique si l’emplacement de destination est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Lignes d’articles dans la transaction</td><td>true</td><td>Articles par produit composant l’historique</td><td>Tous les modes</td></tr><tr><td>items.id</td><td>true</td><td>ID unique de l’article</td><td>true</td><td>ID unique du produit</td><td>Tous les modes</td></tr><tr><td>items.name</td><td>true</td><td>Nom de l’article</td><td>true</td><td>Nom du produit</td><td>Tous les modes</td></tr><tr><td>items.quantity</td><td>true</td><td>Variation de quantité due à la transaction (in/out/adjust/move)</td><td>true</td><td>Quantité d’entrée/sortie/ajustement/transfert pour ce produit</td><td>Tous les modes</td></tr><tr><td>items.deleted</td><td>true</td><td>Indique si l’article est supprimé</td><td>true</td><td>Indique si le produit est supprimé</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Niveau de stock à l’emplacement source après la transaction</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Niveau de stock à l’emplacement de destination après la transaction</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Heure de la transaction (par ex. heure d’entrée/sortie de stock)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Heure à laquelle la transaction a été créée</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Membre qui a créé la transaction</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID unique du membre</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nom du membre</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Indique si le membre est supprimé</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Nombre d’articles</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Quantité totale de variation de stock</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Adresse URL pour consulter la page de détails de la transaction</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Notes liées à la transaction</td><td>false</td><td></td><td></td></tr><tr><td>révision</td><td>true</td><td>Numéro de version actuel de la transaction, à partir de 1</td><td>false</td><td></td><td></td></tr></tbody></table>

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

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

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

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

### `item/new`

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

{% hint style="warning" %}
**Remarque**: Cet événement est *ne* déclenché lors de l’utilisation de la fonctionnalité <mark style="color:bleue;">**`Ajouter des variantes d’article`**</mark> ou lors de l’importation d’articles via <mark style="color:bleue;">**`Importer Excel`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Champ</th><th>Description</th><th data-hidden data-type="checkbox">Obligation</th><th data-hidden>Description</th><th data-hidden>Mode équipe</th></tr></thead><tbody><tr><td>id</td><td>ID de l’article</td><td>true</td><td>ID unique de l’historique</td><td>Tous</td></tr><tr><td>nom</td><td>Nom de l’article</td><td>true</td><td><p>Type de l’historique.</p><ul><li>Entrée : in</li><li>Sortie : out</li><li>Ajustement : adjust</li><li>Transfert : move</li></ul></td><td>Tous</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>code-barres</td><td>Code-barres</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL de la photo</td><td>false</td><td></td><td></td></tr><tr><td>coût</td><td>Coût</td><td>false</td><td></td><td></td></tr><tr><td>prix</td><td>Prix</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributs</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Exemple de charge utile – Article créé**

```json
{
  "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é.

{% hint style="warning" %}
**Remarque**: Cet événement est *ne* déclenché *p*our les modifications groupées effectuées via <mark style="color:bleue;">**`Centre de données`**</mark>**&#x20;>&#x20;**<mark style="color:bleue;">**`Article`**</mark> ou via la <mark style="color:bleue;">**`Importer Excel`**</mark> fonctionnalité.
{% endhint %}

<table><thead><tr><th width="318">Champ</th><th>Description</th><th data-hidden data-type="checkbox">Obligation</th><th data-hidden>Description</th><th data-hidden>Mode équipe</th></tr></thead><tbody><tr><td>id</td><td>ID de l’article</td><td>true</td><td>ID unique de l’historique</td><td>Tous</td></tr><tr><td>nom</td><td>Nom de l’article</td><td>true</td><td><p>Type de l’historique.</p><ul><li>Entrée : in</li><li>Sortie : out</li><li>Ajustement : adjust</li><li>Transfert : move</li></ul></td><td>Tous</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>code-barres</td><td>Code-barres</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL de la photo</td><td>false</td><td></td><td></td></tr><tr><td>coût</td><td>Coût</td><td>false</td><td></td><td></td></tr><tr><td>prix</td><td>Prix</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributs</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Exemple de charge utile – Article mis à jour**

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

{% hint style="warning" %}
**Remarque**: Cet événement est *ne* déclenché pour les suppressions groupées effectuées via <mark style="color:bleue;">**`Centre de données`**</mark>**&#x20;>&#x20;**<mark style="color:bleue;">**`Article`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Champ</th><th>Description</th><th data-hidden data-type="checkbox">Obligation</th><th data-hidden>Description</th><th data-hidden>Mode équipe</th></tr></thead><tbody><tr><td>id</td><td>ID de l’article</td><td>true</td><td>ID unique de l’historique</td><td>Tous</td></tr></tbody></table>

#### Exemple de charge utile **– Article supprimé**

```json
{
  "id": 26122826
}
```