Un webhook WooCommerce jamais reçu : la file d’Action Scheduler en cause

Un logiciel de facturation externe, connecté à une boutique WooCommerce via un webhook sur l’événement « commande créée », n’a plus reçu la moindre notification depuis deux jours. Pourtant, les commandes continuent d’arriver normalement sur la boutique, les clients paient sans problème apparent, et la configuration du webhook, vérifiée à plusieurs reprises dans WooCommerce > Réglages > Avancé > Webhooks, semble parfaitement correcte. Ce billet détaille le diagnostic qui a permis de retrouver la cause réelle, sans aborder la sécurisation de la signature du webhook, un sujet différent qui suppose que le webhook parte au moins correctement.

Un webhook ne part jamais en direct

Le point de départ du diagnostic tient en une phrase souvent méconnue : WooCommerce ne déclenche jamais l’envoi HTTP d’un webhook de manière synchrone, au moment précis de l’événement. L’envoi est délégué à Action Scheduler, la bibliothèque de tâches planifiées partagée par WooCommerce et de nombreuses extensions. Concrètement, la création d’une commande programme une action woocommerce_webhook_should_deliver, elle-même exécutée plus tard, lors du passage suivant du planificateur.

Où regarder en premier

L’écran WooCommerce > État > Outils avancés > Actions planifiées (accessible aussi via wp-admin/admin.php?page=wc-status&tab;=action-scheduler) liste toutes les actions en attente, en cours d’exécution, terminées ou en échec. Sur ce cas précis, le filtre par statut « en attente » (pending) affichait plusieurs centaines d’actions accumulées, bien au-delà du volume normal d’une journée de commandes.

wp action-scheduler list --status=pending --per-page=20

Cette commande WP-CLI confirme la même chose depuis le terminal, particulièrement utile quand l’accès à l’interface d’administration devient lui-même trop lent à cause de l’accumulation.

Diagnostic : pourquoi la file s’est bloquée

En creusant la liste des actions bloquées, un motif se dégageait : de nombreuses actions woocommerce_webhook_should_deliver restaient au statut in-progress sans jamais passer à complete. Action Scheduler considère par défaut qu’une action bloquée plus de dix minutes en in-progress doit être retentée, mais un réglage de délai anormalement long côté serveur de facturation externe — celui-ci mettait plusieurs minutes à répondre lors d’un pic de charge — provoquait un embouteillage progressif de la file.

wp action-scheduler list --status=in-progress --per-page=20

Chaque webhook en attente de réponse du serveur distant occupait un slot d’exécution du cron WooCommerce, retardant d’autant tous les webhooks suivants, y compris ceux destinés à d’autres intégrations sans aucun rapport avec le logiciel de facturation en cause.

Le vrai coupable : un timeout HTTP trop généreux

WooCommerce envoie ses webhooks avec un délai d’expiration configurable, mais souvent laissé à sa valeur par défaut. Un serveur distant lent, sans répondre d’erreur explicite, laisse la requête ouverte jusqu’à expiration de ce délai, bloquant la ressource d’exécution du cron pendant toute cette durée :

add_filter( 'woocommerce_webhook_http_args', function( $http_args, $arg, $id ) {
    $http_args['timeout'] = 15;
    return $http_args;
}, 10, 3 );

Réduire ce délai à une valeur raisonnable n’empêche pas l’incident côté serveur distant, mais évite qu’un seul service lent ne paralyse toute la file de livraison des webhooks de la boutique.

Vider la file accumulée sans perdre de données

1. Confirmer d’abord, avec le service de facturation externe, qu’aucune de ces commandes n’a en réalité déjà été reçue par un autre canal.
2. Relancer les actions en échec directement depuis l’écran d’administration, plutôt que de les supprimer, pour ne perdre aucune commande.
3. Surveiller le nombre d’actions en attente dans les heures suivantes pour confirmer un retour à un volume normal.
4. Vérifier que le cron WordPress s’exécute suffisamment souvent : un site à faible trafic, sans visite régulière, peut lui-même ralentir le déclenchement du cron basé sur les requêtes entrantes.

Une astuce qui a fait gagner du temps sur ce diagnostic : filtrer directement les actions par leur groupe webhooks dans l’écran Action Scheduler, plutôt que de parcourir toutes les actions planifiées de la boutique, souvent nombreuses avec Action Scheduler mutualisé entre plusieurs extensions.

Prévention pour la suite

Sur ce projet, une surveillance a été mise en place via une action planifiée quotidienne qui compte les actions en attente du groupe webhooks et alerte par e-mail si ce nombre dépasse un seuil anormal, plutôt que d’attendre qu’un client externe signale lui-même l’absence de données reçues. Ce type de garde-fou coûte peu à mettre en place et évite qu’un incident similaire ne passe inaperçu pendant deux jours entiers avant d’être détecté.

En résumé

Un webhook WooCommerce « jamais reçu » n’est presque jamais un problème de configuration du webhook lui-même : c’est le plus souvent un symptôme d’une file Action Scheduler engorgée, provoquée par un service distant trop lent à répondre. Le réflexe de diagnostic à retenir consiste à regarder d’abord l’état de la file avant de suspecter la configuration ou le code applicatif.