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.
{
"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-Sourceindique l’URL du site émetteurX-WC-Webhook-Delivery-IDdistingue 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.
