Webhooks WooCommerce en échec : comment les diagnostiquer

Symptômes

• Le système destinataire ne reçoit jamais certains événements, ou aucun.
• Les événements arrivent avec des minutes ou des heures de retard.
• Le statut du webhook est passé à Désactivé sans que personne n’y touche.
• Le destinataire traite deux fois la même commande.
• Le destinataire rejette les livraisons comme non authentifiées.

Causes les plus fréquentes

1. Le destinataire échoue : il renvoie 4xx/5xx à cause de ses propres bugs, de règles d’authentification ou d’une validation de payloads inattendus.
2. Le destinataire est trop lent : il fait tout son travail avant de répondre et la requête expire.
3. Quelque chose bloque la livraison : le pare-feu, le WAF ou la liste d’IP autorisées du destinataire ; ou l’hébergeur de la boutique qui bloque les requêtes sortantes.
4. La vérification de signature est fausse : calculée sur le JSON déjà décodé au lieu du corps brut, ou avec un ancien secret.
5. Le traitement de fond est bloqué : Action Scheduler ou WP-Cron ne s’exécute pas, et les livraisons s’accumulent.
6. Les destinataires ne sont pas idempotents : order.updated se déclenche à de nombreux enregistrements et les reprises renvoient des événements, donc la même commande arrive plusieurs fois.

Diagnostic

1. Vérifiez le statut et les journaux de livraison

Dans WooCommerce → Réglages → Avancé → Webhooks, vérifiez le statut (Actif, En pause, Désactivé), le sujet et l’URL de livraison. Consultez ensuite WooCommerce → État → Journaux pour le journal de livraison des webhooks, qui enregistre chaque livraison avec son code de réponse et sa durée.

2. Vérifiez la file

Les livraisons s’exécutent comme actions woocommerce_deliver_webhook_async. Dans Outils → Actions planifiées, cherchez ce hook : beaucoup d’actions En attente ou en retard signifient que la file n’est pas traitée ; les actions Échouées contiennent l’erreur.

3. Vérifiez le destinataire

Côté destinataire, journalisez la requête brute, les en-têtes et la réponse renvoyée pour une livraison de test. WooCommerce envoie des en-têtes utiles : X-WC-Webhook-Topic, X-WC-Webhook-Resource, X-WC-Webhook-ID, X-WC-Webhook-Delivery-ID et X-WC-Webhook-Signature.

Journaux et vérifications techniques

• Réglages du webhook : statut, sujet, URL de livraison, secret, version de l’API.
• Journaux WooCommerce pour les livraisons de webhooks.
• Outils → Actions planifiées : actions de livraison en attente, en retard et échouées.
• Journaux du destinataire : corps brut, en-têtes, code de réponse, temps de traitement.
• Pare-feu des deux côtés : requêtes sortantes de la boutique, entrantes chez le destinataire.

Solutions

• Répondez vite, traitez ensuite : le destinataire doit vérifier la signature, stocker l’événement et renvoyer 200 immédiatement, puis le traiter dans sa propre file.
• Vérifiez les signatures sur le corps brut :

$payload   = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$expected  = base64_encode( hash_hmac( 'sha256', $payload, WEBHOOK_SECRET, true ) );

if ( ! hash_equals( $expected, $signature ) ) {
    http_response_code( 401 );
    exit;
}

// Stocker l’événement, renvoyer 200 tout de suite, le traiter en asynchrone.

• Acceptez le ping que WooCommerce envoie à l’enregistrement d’un webhook (données de formulaire avec webhook_id) et renvoyez 200.
• Rendez le traitement idempotent : utilisez l’identifiant de livraison et l’identifiant de la ressource avec sa date de modification pour ignorer les événements déjà appliqués.
• Faites avancer la file : assurez-vous que WP-Cron s’exécute, de préférence depuis une vraie tâche cron du serveur, et résorbez toute accumulation d’Action Scheduler.
• Réactivez le webhook après avoir corrigé le destinataire : repassez son statut en Actif.

Ce qu’il ne faut pas faire

• Ne sautez pas la vérification de signature côté destinataire ; n’importe qui pourrait lui envoyer de fausses commandes.
• N’exécutez pas de travail lent (appels ERP, e-mails, génération de PDF) avant de répondre au webhook.
• Ne réactivez pas sans cesse un webhook désactivé sans corriger le destinataire ; il sera de nouveau désactivé.
• Ne supprimez pas les actions de livraison en attente pour « faire le ménage » : ce sont des événements que le destinataire n’a pas encore vus.

Quand faire appel à un expert

Faites appel à un ingénieur quand l’intégration perd ou duplique des commandes, quand vous ne contrôlez qu’un côté de l’intégration et avez besoin de preuves pour l’autre, ou quand le destinataire doit être reconstruit pour être rapide, vérifié et idempotent.

Problèmes liés

• WooCommerce / Performance Problèmes d’Action Scheduler dans WooCommerce Actions planifiées en retard, échouées et bloquées : comment la file fonctionne, pourquoi elle s’arrête et comment la réparer sans perdre de travail en attente. →
• WooCommerce / Intégrations Erreurs de l’API REST WooCommerce : comment les diagnostiquer Lisez le code de statut et le code d’erreur de la réponse : authentification, permissions, routage, couches de sécurité et erreurs serveur échouent chacun à leur manière. →
• WooCommerce / Paiements WooCommerce : paiement échoué mais client débité Quand la passerelle encaisse le paiement mais que la commande reste en attente ou échouée, vérifiez le relais des callbacks et des webhooks avant de toucher à la commande. →

Questions fréquentes