Réactiver un webhook sortant désactivé par WooCommerce

Identifier la notification sortante qui s’est arrêtée

Votre boutique continue à enregistrer des modifications, mais l’application qui doit les recevoir ne se met plus à jour. Dans WooCommerce, le webhook apparaît comme Désactivé. Un webhook envoie une notification HTTP à une adresse de livraison lorsqu’un événement correspond au sujet choisi. Cette procédure concerne la notification native qui part de votre boutique vers un autre service. Les notifications que votre prestataire de paiement adresse à la boutique se diagnostiquent depuis l’intégration de paiement.

WooCommerce peut désactiver un webhook après des échecs consécutifs. Le seuil peut dépendre de la version et de la configuration. Commencez par retrouver une tentative et sa réponse avant de remettre le webhook en service. Si son statut est En pause, cherchez la raison de cette pause auprès de la personne qui l’a décidée. Un webhook actif sans tentative récente appelle une vérification du sujet et de la file de tâches.

Le résultat attendu comprend une nouvelle livraison acceptée par le bon destinataire et une preuve que l’événement a été traité comme prévu. Il faut généralement un accès aux réglages WooCommerce et une personne capable de lire le journal du service récepteur.

Relever la configuration du webhook concerné

Dans WooCommerce, ouvrez Réglages puis Avancé et Webhooks. Sélectionnez la ligne correspondant à l’intégration touchée et relevez son identifiant, son statut, son sujet et son adresse de livraison. Les noms peuvent être proches pour deux magasins ou deux environnements. Utilisez l’identifiant et le sujet pour reconnaître la bonne ligne, puis comparez son domaine avec celui que le responsable du service attend.

Notez le dernier changement connu. Il peut s’agir d’une migration du destinataire, d’une rotation de secret, d’un changement du chemin ou du déploiement d’une nouvelle version. Faites une copie privée des réglages utiles, en conservant les secrets dans leur espace prévu. Une adresse peut contenir un jeton dans son chemin ou ses paramètres. Masquez ces parties dans les captures et les tickets ordinaires.

1. Relevez la version installée, l’heure des derniers événements connus et le nom de l’environnement.
2. Identifiez l’ID et le sujet du webhook, puis confirmez qui exploite son destinataire.
3. Notez le statut initial et la destination prévue pour le retour.
4. Préparez une copie isolée dont les notifications et les actions commerciales réelles sont neutralisées.

Relier une livraison à la trace du destinataire

Dans WooCommerce, ouvrez État puis Journaux. Filtrez les sources sur webhooks-delivery, puis cherchez l’heure et la destination du webhook. Relevez le code de réponse, le message et l’identifiant de livraison quand ils figurent dans la trace. Demandez au responsable du destinataire de vérifier la même période et le même événement dans ses propres journaux. Une ligne côté boutique et une ligne côté récepteur permettent de situer l’échec bien mieux qu’un statut seul.

Les journaux peuvent contenir des en-têtes, des adresses et des données de commande. Gardez la lecture privée et transmettez seulement les détails nécessaires. Selon la version et les réglages, le corps peut ne pas être enregistré. Évitez d’activer le mode de débogage en production pour remplir un ticket. Cherchez plutôt un exemple non sensible sur la copie.

Si le journal manque, contrôlez la rétention et la configuration des journaux avant de conclure que la boutique n’a rien envoyé. Si l’action est encore dans la file, il peut aussi n’y avoir aucune réponse HTTP à relever pour cette tentative. Utilisez l’heure et le sujet pour continuer le diagnostic.

Classer la réponse avant de corriger la boutique

Une erreur de connexion sans code HTTP et une réponse émise par le destinataire appellent des vérifications différentes. Pour chacune, conservez l’heure et cherchez la trace sur la couche qui peut avoir répondu. Une page de connexion, un pare-feu et l’application peuvent tous renvoyer une réponse à la même URL.

La livraison courante de WooCommerce 11.2.1 n’active pas le suivi des redirections dans ses paramètres par défaut. Une redirection peut pourtant être comptée comme succès par la boutique. Un statut de cette famille ne garantit donc pas que le POST a atteint la route finale. Demandez une réponse directe de la route prévue et confirmez la réception dans l’application.

1. Avec un 404 ou un 405, vérifiez le chemin et la méthode POST attendue.
2. Avec un 401 ou un 403, cherchez la règle ou la vérification précise qui refuse la requête.
3. Avec un 429, identifiez la limite de débit et la période concernée avant de réactiver.
4. Avec un 5xx ou un délai dépassé, vérifiez les traces du serveur et l’état éventuel du traitement.
5. En cas d’erreur DNS ou TLS, faites contrôler l’accès depuis le trajet utilisé par la boutique.

Corriger l’adresse ou la règle qui bloque le trajet

Ouvrez les réglages du webhook concerné et comparez l’URL de livraison avec l’URL finale donnée par le responsable du récepteur. Vérifiez le protocole, le domaine, le chemin et les paramètres nécessaires. Après une migration, une ancienne adresse peut répondre par une redirection ou une page d’accueil. Une ouverture réussie dans votre navigateur valide seulement ce parcours de lecture. Le webhook doit pouvoir faire son POST depuis le réseau de la boutique.

Pour un refus par un pare-feu, demandez l’identifiant de la règle et vérifiez qu’elle correspond à cette tentative. Adaptez le chemin ou l’autorisation de la seule route avec le responsable. Gardez la vérification de signature et les contrôles d’accès utiles. Si le certificat de la destination est en cause, faites corriger celui que la boutique reçoit avant de reprendre les livraisons.

Sur la copie autorisée, modifiez le champ URL de livraison et gardez le sujet d’origine pour isoler cette correction. Préparez un destinataire de test avant d’enregistrer un webhook actif. Si la nouvelle adresse échoue, revenez à la valeur sauvegardée uniquement si elle est toujours valide et autorisée.

Comparer la signature avant de modifier le secret

Si le récepteur dit que la signature est invalide, identifiez d’abord le secret associé à ce webhook précis et le corps effectivement reçu. Par défaut, WooCommerce calcule un HMAC SHA-256 sur les octets envoyés, puis encode le résultat en Base64 dans X-WC-Webhook-Signature. Décoder puis réencoder le JSON peut changer les espaces, les caractères échappés ou leur représentation. Calculez la signature avant de transformer le corps.

Ce fragment est destiné au développeur d’un récepteur PHP existant qui utilise cet algorithme par défaut. Dans sa fonction de validation, reliez les paramètres au corps brut, à la valeur de l’en-tête et au secret effectif lu depuis sa configuration privée. Utilisez une chaîne vide si l’en-tête manque. Le secret doit être configuré et rester hors du code, des traces et des réponses. Un résultat faux doit empêcher le traitement de l’événement signé.

Sur la copie, vérifiez qu’un événement autorisé passe et qu’un corps modifié est refusé. Si un changement de secret est nécessaire, coordonnez l’activation des deux côtés et gardez une procédure de retour avec le responsable. Pour un récepteur géré par un service tiers, utilisez le mécanisme de secret prévu par ce service.

function signature_woocommerce_valide(
    string $corpsBrut,
    string $signatureRecue,
    string $secretEffectif
): bool {
    if ($secretEffectif === '') {
        return false;
    }

    $attendue = base64_encode(hash_hmac('sha256', $corpsBrut, $secretEffectif, true));
    return hash_equals($attendue, $signatureRecue);
}

Corriger le traitement lorsque le récepteur reçoit déjà le POST

Une trace du récepteur peut montrer que le POST est arrivé et que la vérification d’accès a réussi, puis qu’une erreur survient dans l’application. Par exemple, une modification du format attendu, un enregistrement impossible ou une file interne indisponible peut provoquer une réponse 5xx. Cherchez l’étape exacte dans la trace du service avant de changer le sujet ou le secret dans WooCommerce.

Comparez la charge reçue avec le format que le récepteur accepte. Faites la reproduction avec un événement synthétique et des données de test. Si le service traite une tâche plus tard, assurez-vous que l’événement est enregistré durablement avant l’accusé de réception. Une réponse envoyée trop tôt peut masquer une perte dans la file du destinataire. À l’inverse, un délai réseau peut survenir après un traitement réussi. Dans ce cas, contrôlez l’état métier avant d’envisager un nouvel envoi.

Si vous revenez à une version antérieure du destinataire, vérifiez qu’elle reconnaît le format actuel et qu’elle peut lire les données déjà écrites. Surveillez la trace du même événement. Une disparition du message d’erreur seule ne démontre pas que la mise à jour attendue a été enregistrée.

Vérifier les actions planifiées si aucune tentative ne part

Si le webhook est actif et que le sujet correspond à un événement récent, ouvrez WooCommerce puis État et Actions planifiées. Dans la version étudiée, le parcours de fond utilise l’action woocommerce_deliver_webhook_async et le groupe woocommerce-webhooks par défaut. Les installations personnalisées peuvent suivre un autre trajet. Cherchez ce nom et, si le détail est disponible, comparez l’identifiant du webhook et l’argument avec votre témoin.

Une action en attente peut indiquer que la livraison n’a pas encore démarré. Une action terminée indique que son traitement a pris fin du point de vue du planificateur. Vérifiez encore le résultat HTTP et le destinataire. Pour un retard plus large qui touche d’autres actions, utilisez le diagnostic du planificateur au lieu de relever le seuil du webhook.

1. Recherchez les actions liées au seul webhook concerné et relevez leurs états.
2. Comparez leur heure avec le journal des livraisons.
3. Distinguez une file en attente d’une tentative déjà envoyée.
4. Avant toute reprise, vérifiez les événements déjà traités et les actions encore présentes. Évitez la relance en masse.

Réactiver la ligne concernée après la correction

Préparez le destinataire et vérifiez que le test ne peut déclencher ni paiement, ni expédition, ni message réel. Sur la copie, revenez dans WooCommerce, Réglages, Avancé et Webhooks. Ouvrez la ligne choisie, confirmez son sujet et son URL, puis passez son statut à Actif et enregistrez. La première activation peut déclencher une requête de vérification. Ce ping peut différer d’un événement normal et son succès ne remplace pas la preuve de traitement du témoin.

Quand la cause est corrigée et le comportement validé sur la copie, appliquez le même changement ciblé selon la procédure de la boutique. Contrôlez l’état après sauvegarde. En cas de message d’erreur, relisez l’état réellement enregistré et la trace du récepteur avant de recommencer. Le formulaire peut avoir enregistré des paramètres avant de signaler un problème de ping.

1. Confirmez le webhook, la destination et le secret effectif avec le responsable.
2. Réactivez seulement la ligne concernée.
3. Relevez l’heure et contrôlez les premières tentatives.
4. Si le défaut revient, remettez la ligne en pause et examinez les actions encore en file avec l’exploitant. Le changement de statut ne prouve pas que la file est vide.

Vérifier un événement du bon sujet de bout en bout

Sur la copie, produisez un seul événement compatible avec le sujet du webhook. Pour une notification de mise à jour de produit, modifiez un champ d’un produit de test déjà existant. Pour un sujet de commande, utilisez une commande fictive dans un environnement où les paiements, courriels et expéditions réels sont neutralisés. Le témoin doit atteindre le même type de route et de traitement que l’événement concerné.

Comparez les preuves des deux côtés. Relevez le statut HTTP de la livraison et l’identifiant de l’objet, puis retrouvez la trace correspondante dans le destinataire. Vérifiez aussi l’état après traitement. Si l’application ajoute l’événement à sa propre file, attendez son traitement et confirmez la mise à jour prévue. La réponse de la route ne remplace pas ce contrôle.

Sur la boutique publique, vérifiez les prochains événements normaux à partir de leurs journaux. Si les premières tentatives réussissent et que les mises à jour suivent, continuez la surveillance sur le sujet concerné. Si le compteur recommence à accumuler des échecs ou que le destinataire ignore les événements, revenez à l’étape indiquée par les traces.

Rapprocher les événements manqués avant tout renvoi

La remise en service relance le flux normal des événements à venir. Pour la période où le webhook était arrêté, établissez ce que la boutique a modifié et ce que l’autre service a réellement reçu. Une tentative en échec apparent a pu être traitée avant que la réponse se perde. Une action peut aussi rester en attente. Comparez les identifiants métier, les types d’événement et les états, en tenant compte de l’heure et des mises à jour ultérieures.

Choisissez avec le destinataire sa procédure documentée pour combler les écarts. Une synchronisation de l’état actuel peut suffire pour un catalogue. Un traitement sensible aux transitions exige de vérifier l’ordre et les effets de chaque événement avant de le rejouer. La clé de dédoublonnage doit être adaptée à ce traitement. Le même produit peut avoir plusieurs mises à jour légitimes.

1. Délimitez la période et les ressources concernées.
2. Séparez les éléments confirmés, absents et encore incertains.
3. Vérifiez les actions en attente avant tout renvoi ciblé.
4. Contrôlez le résultat côté destinataire après chaque rattrapage sensible. Gardez une trace des décisions et de la personne qui les a validées.

Prévenir un nouvel arrêt après une migration ou une rotation

Dans le dossier d’exploitation de la boutique, notez pour chaque webhook son propriétaire, son sujet, le destinataire et le canal de gestion du secret. Après une migration, confirmez l’adresse finale et le traitement du POST avec le responsable du service. Lors d’une rotation de secret, choisissez une fenêtre et prévoyez la coordination des deux extrémités. Vérifiez le premier événement valide après le changement.

Les webhooks décrits font partie du module gratuit WooCommerce, dans sa version 11.2.1 prise comme référence dans ce guide. Les conditions d’un récepteur tiers dépendent du contrat déjà utilisé. Pour ce dépannage, vérifiez d’abord le journal, la destination et la configuration du récepteur existant. Une modification du seuil peut retarder le prochain arrêt tout en laissant subsister la cause des échecs.

Conservez des traces qui permettent de rapprocher les livraisons sans recopier les données des clients. Lorsque le destinataire assure des opérations sensibles, notez comment vérifier leur état avant de rejouer un événement. Si l’incident revient, remettez au responsable l’ID du webhook, l’heure, le statut et l’étape précise où la trace s’interrompt.