Un webhook WooCommerce est un message que votre boutique envoie à un autre service quand quelque chose se produit, par exemple quand une commande est créée ou mise à jour. Vous le configurez une seule fois sous WooCommerce, Réglages, Avancé, Webhooks : vous choisissez l'événement (le sujet), l'adresse de destination (l'URL de livraison) et un secret qui sert à signer chaque message. Dès lors, WooCommerce envoie la commande à cette adresse chaque fois que l'événement se déclenche. La plupart des problèmes viennent de quatre sources : le mauvais sujet, un secret différent de chaque côté, un webhook sans utilisateur autorisé à lire les commandes, et des livraisons en pause ou retardées.
Ce guide explique chaque champ en termes simples, puis passe en revue ces erreurs.
Ce qu'est un webhook, du point de vue d'une boutique
Voyez-le comme un e-mail automatique entre deux systèmes. Au lieu qu'une personne consulte vos commandes et les recopie quelque part, WooCommerce envoie chaque commande à un service dès qu'elle change. Ce service peut être un outil de comptabilité, un prestataire logistique ou un widget de notifications de ventes.
Deux choses rendent cette méthode meilleure qu'une copie manuelle ou un export nocturne :
- C'est immédiat. Le service destinataire est informé d'une commande en quelques instants.
- C'est vérifiable. Avec un secret, le destinataire peut prouver que le message vient de votre boutique et n'a pas été modifié en chemin.
Les champs de l'écran des webhooks
| Champ |
Ce qu'il signifie |
Que saisir |
| Nom |
Un libellé pour vous |
Quelque chose qui indique la destination, par exemple « Commandes vers Provedly » |
| État |
Actif, En pause ou Désactivé |
Actif, une fois prêt |
| Sujet |
L'événement qui déclenche une livraison |
Généralement un sujet de commande, voir ci-dessous |
| URL de livraison |
L'adresse où WooCommerce envoie le message |
L'adresse fournie par le service destinataire, commençant par https |
| Secret |
Une valeur partagée qui sert à signer chaque message |
Une longue valeur que vous collez aussi dans le service destinataire |
| Version de l'API |
Le format du message |
La version actuelle de l'API REST WP, sauf indication contraire du service |
Un réglage n'apparaît pas sous forme de champ mais compte beaucoup : chaque webhook appartient à un utilisateur WordPress. WooCommerce construit chaque livraison en lisant la commande via sa propre API REST, en tant que cet utilisateur. Si l'utilisateur ne peut pas lire les commandes, la livraison contient une erreur au lieu de la commande.
order.created ou order.updated
C'est sur ces deux sujets que la plupart des configurations dérapent.
- order.created se déclenche une seule fois, quand la commande est enregistrée pour la première fois. Pour de nombreux moyens de paiement, cela se produit avant que le client ait payé : la commande peut donc être encore en Attente de paiement.
- order.updated se déclenche à chaque modification de la commande : quand le paiement passe et que le statut devient En cours, quand vous la marquez Terminée, quand vous ajoutez une note.
Si vous voulez agir uniquement sur les commandes payées, order.created seul peut manquer le moment du paiement, et peut envoyer des commandes qui ne seront jamais payées. order.updated voit le paiement, mais il envoie aussi la même commande plusieurs fois. La solution habituelle consiste à écouter order.updated et à demander au service destinataire deux choses : ignorer les commandes dont le statut n'est pas payé, et mémoriser les identifiants de commande déjà traités.
C'est exactement ce que fait Provedly avec WooCommerce. Il n'enregistre une commande que si son statut est En cours ou Terminée, et n'enregistre chaque identifiant de commande qu'une fois, quel que soit le nombre de mises à jour reçues. Il accepte aussi les livraisons order.created, avec les mêmes règles.
Le secret et la signature
Quand un webhook a un secret, WooCommerce passe le corps du message et le secret dans une fonction de hachage (HMAC-SHA256) et envoie le résultat dans un en-tête appelé X-WC-Webhook-Signature. Le service destinataire fait le même calcul avec sa copie du secret. Si les deux résultats correspondent, le message vient de quelqu'un qui connaît le secret et n'a pas été modifié en chemin. S'ils diffèrent, le service doit rejeter le message.
Points pratiques :
- Le secret doit être identique des deux côtés, majuscules comprises et sans espaces en trop.
- Choisissez une valeur longue et aléatoire, et gardez-la hors des captures d'écran et des tickets de support.
- Le changer d'un côté interrompt les livraisons jusqu'à ce que vous le changiez de l'autre.
C'est la signature qui permet à une notification de ventes d'afficher honnêtement « Achat vérifié ». Sans elle, quiconque connaîtrait l'URL de livraison pourrait envoyer une commande inventée. Notre article sur les secrets de signature de webhook compare les méthodes de Stripe, Shopify et WooCommerce.
Erreurs courantes et solutions
| Ce que vous voyez |
Cause |
Solution |
| Le service destinataire reçoit une erreur de l'API REST au lieu de la commande, souvent liée aux permissions |
L'utilisateur du webhook ne peut pas lire les commandes, ou le webhook a été créé par un script sans utilisateur |
Assurez-vous qu'un administrateur est propriétaire du webhook. L'extension Provedly en assigne un quand elle crée le webhook |
| « Invalid signature » dans le journal de livraison |
Les secrets diffèrent |
Collez le même secret des deux côtés |
| Rien n'arrive |
Le webhook est En pause ou Désactivé, ou l'URL de livraison contient une faute de frappe |
Passez-le à Actif et recopiez l'URL |
| Le webhook est passé tout seul à Désactivé |
WooCommerce désactive un webhook après des échecs de livraison répétés |
Corrigez la cause, puis repassez-le à Actif |
| Les commandes arrivent avec plusieurs minutes de retard |
Les livraisons sont mises en file d'attente comme tâches de fond, exécutées quand le site reçoit du trafic ou via une tâche planifiée |
Vérifiez WooCommerce, État, Actions planifiées pour les tâches de webhook en attente |
| Des commandes impayées apparaissent dans un autre outil |
Le sujet est order.created et l'outil ne vérifie pas le statut |
Utilisez order.updated, et filtrez par statut |
WooCommerce conserve un journal des livraisons sous WooCommerce, État, Journaux. Il montre la réponse renvoyée par le service destinataire, ce qui est généralement le moyen le plus rapide de voir ce qui n'a pas fonctionné.
Quand vous créez un nouveau webhook, WooCommerce envoie un court « ping » de test à l'URL de livraison. Un destinataire bien conçu y répond pour que le webhook puisse s'activer ; ce ping ne contient pas de commande.
Le faire avec Provedly
Vous n'avez rien à configurer à la main. L'extension Provedly, gratuite, crée le webhook quand vous collez l'URL de livraison et le secret sur sa page de réglages et cliquez sur Enregistrer : sujet order.updated, version actuelle de l'API, actif, signé avec votre secret, appartenant à un administrateur. Notre guide des notifications de ventes récentes WooCommerce détaille la configuration.
Questions fréquentes
Ai-je besoin d'un secret sur mon webhook WooCommerce ?
Pas pour que WooCommerce l'envoie, mais vous devriez toujours en définir un quand le destinataire le prend en charge. Sans secret, le destinataire ne peut pas distinguer les messages de votre boutique de ceux de n'importe qui d'autre, et une notification de ventes fondée sur des messages non signés ne peut pas honnêtement être qualifiée de vérifiée.
Puis-je avoir plusieurs webhooks pour les commandes ?
Oui. Chaque service reçoit son propre webhook avec sa propre URL de livraison et son propre secret. Ils n'interfèrent pas entre eux, et mettre l'un en pause laisse les autres fonctionner.
Un nouveau webhook enverra-t-il mes anciennes commandes ?
Non. Un webhook se déclenche sur les événements qui surviennent après sa création : les anciennes commandes ne sont envoyées que si elles changent, par exemple quand vous en marquez une comme Terminée. Pour importer l'historique, utilisez plutôt l'option d'import du service destinataire.
Connectez vos commandes WooCommerce via un webhook signé avec l'offre gratuite de Provedly en créant un compte.