> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/fr/integrations/webhook.md).

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

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## Enregistrement

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

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

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

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

> **Note**
>
> Si vous avez besoin de sujets d’événements supplémentaires, veuillez contacter le [support](https://www.boxhero.io/docs/fr/resources/contact).

### txs/new

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

> **Caution**
>
> **Remarque :** cet événement n’est _pas_ déclenché pour les ajustements créés par des modifications groupées ou des importations (p. ex. 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) |
| 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

```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 de webhook – Événement Move Stock

```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": "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

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

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

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

### item/new

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

> **Caution**
>
> **Remarque** : cet événement n’est _pas_ déclenché lors de l’utilisation de la fonctionnalité `Ajouter des variantes d'articles` ou de l’importation d’articles via `Importer depuis Excel`.

| 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éé

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

> **Caution**
>
> **Remarque** : cet événement n’est _pas_ déclenché pour les modifications groupées effectuées via `Centre de données` > `Article` ou via la fonction `Importer depuis Excel`.

| 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

```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": "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.

> **Caution**
>
> **Remarque** : cet événement n’est _pas_ déclenché pour les suppressions groupées effectuées via `Centre de données` > `Articles`.

| Champ | Description |
| --- | --- |
| id | ID de l’article |

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

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