# Les webhooks WooCommerce en détail : événements et format de charge utile

> Panorama complet des événements disponibles côté webhooks WooCommerce et du format exact de la charge utile envoyée à un système tiers.

- Auteur : Clément Hadrot
- Publié le : 2023-12-19
- Mis à jour le : 2023-12-19
- Catégorie : E-commerce
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ecommerce/webhooks-woocommerce-evenements-charge-utile/

## L’essentiel

- Six ressources déclenchent des événements par défaut
- Le corps JSON reprend la structure de l'API REST
- Un délai de nouvelle tentative existe en cas d'échec

Un webhook, dans WooCommerce, n'est rien de plus qu'une notification HTTP envoyée à une URL choisie chaque fois qu'un événement précis se produit sur la boutique. C'est un mécanisme simple sur le papier, mais dont la richesse réelle — la liste des événements disponibles, la structure exacte de ce qui est envoyé, le comportement en cas d'échec — reste mal documentée pour qui doit connecter un ERP, un CRM ou un outil de facturation externe.

Cet article détaille ce qu'un développeur en intégration a réellement besoin de savoir avant de brancher un système tiers sur les webhooks WooCommerce : quels événements existent, ce que contient la charge utile, et comment WooCommerce gère les tentatives ratées.

## Les ressources qui déclenchent des webhooks

WooCommerce expose des webhooks pour six types de ressources principales, chacune avec ses propres événements : `commande`, `produit`, `client`, `coupon`. Chaque ressource propose en général quatre variantes d'événement : *created*, *updated, deleted* et *restored* pour ce qui repose sur la corbeille WordPress. Une commande, par exemple, expose `order.created`, `order.updated` et `order.deleted`, configurables individuellement dans WooCommerce, sous *Réglages > Avancé > Webhooks*.

Il existe aussi une topic spécifique moins connue, `action`, qui permet de brancher un webhook sur n'importe quel hook WordPress arbitraire déclaré côté PHP, pas seulement sur les six ressources standard. C'est la porte d'entrée la plus flexible, mais aussi la moins outillée : le format de charge utile n'est alors plus garanti par WooCommerce lui-même.

## La structure exacte de la charge utile

Pour les topics standard, le corps de la requête POST envoyée au système tiers reprend très exactement la structure retournée par l'endpoint correspondant de l'API REST WooCommerce. Un webhook `order.updated` envoie donc le même JSON que celui que renverrait une requête `GET /wp-json/wc/v3/orders/{id}`, avec tous les champs standards : `id`, `status`, `total`, `line_items`, `billing`, `shipping`, jusqu'aux métadonnées personnalisées exposées via `register_rest_field`.

> L'essentiel à retenir : Six ressources déclenchent des événements par défaut ; Le corps JSON reprend la structure de l'API REST ; Un délai de nouvelle tentative existe en cas d'échec

```
{
  "id": 4821,
  "status": "processing",
  "currency": "EUR",
  "total": "129.90",
  "line_items": [
    {
      "id": 12,
      "name": "Etagere murale chene",
      "product_id": 305,
      "quantity": 1,
      "total": "129.90"
    }
  ],
  "billing": {
    "email": "client@exemple.fr",
    "city": "Nantes"
  }
}
```

## Les en-têtes HTTP à ne pas ignorer

Chaque requête webhook porte plusieurs en-têtes utiles pour le système récepteur : `X-WC-Webhook-Topic` précise l'événement exact, `X-WC-Webhook-Resource` et `X-WC-Webhook-Event` le décomposent, `X-WC-Webhook-ID` identifie le webhook configuré côté WordPress, et `X-WC-Webhook-Delivery-ID` identifie la tentative précise, ce qui est précieux pour dédupliquer côté récepteur si une nouvelle tentative arrive après un premier traitement partiel.

- `X-WC-Webhook-Source` indique l'URL du site émetteur
- `X-WC-Webhook-Delivery-ID` distingue chaque tentative d'une même notification
- Le corps est toujours envoyé en JSON, quel que soit le réglage de format côté site

## Le comportement en cas d'échec

Si le point d'entrée distant répond par un code d'erreur ou ne répond pas dans le délai imparti, WooCommerce retente l'envoi selon une logique de nouvelles tentatives intégrée à `WC_Webhook`. Après cinq échecs consécutifs sur un même webhook, celui-ci est automatiquement désactivé et son statut passe à *en pause* dans l'interface d'administration, ce qui évite de marteler indéfiniment un endpoint distant en panne, mais impose une vérification manuelle régulière côté maintenance.

Ce détail a des conséquences pratiques : un ERP indisponible une nuit entière peut suffire à désactiver silencieusement la synchronisation des commandes, sans qu'aucune alerte visible ne remonte ailleurs que dans le journal des webhooks. Beaucoup d'équipes découvrent ce comportement après plusieurs jours de désynchronisation, pas avant.

## Le journal des livraisons, souvent sous-exploité

Chaque webhook conserve un historique de ses dernières livraisons, consultable directement depuis sa fiche dans l'administration : code de réponse HTTP, contenu envoyé, contenu reçu en retour. C'est l'outil de diagnostic le plus rapide en cas d'incohérence signalée par le système tiers, bien avant de chercher dans les journaux serveur.

> Avant de suspecter un bug côté ERP, ouvrez toujours le journal de livraison du webhook concerné : neuf fois sur dix, la réponse HTTP reçue explique tout.

## Pour aller plus loin

Comprendre la mécanique des webhooks WooCommerce évite bien des allers-retours de débogage lors d'une intégration : savoir que la charge utile reprend le format de l'API REST permet de réutiliser directement la documentation de cette dernière, et connaître la limite de cinq tentatives incite à mettre en place une supervision côté système tiers plutôt que de faire une confiance aveugle à la boutique pour signaler ses propres pannes de livraison.