Black Friday · Cyber MondayJusqu’à 50 % de réduction sur les formules annuelles !J’en profite→

Webhook : définition

Message HTTP automatisé qu’un service envoie à votre boutique pour la notifier d’un événement en temps réel.

Définition

Un webhook est une notification de serveur à serveur : quand un événement survient dans un service (passerelle de paiement, API tierce), ce service envoie une requête HTTP POST à une URL que vous avez indiquée, avec le détail de l’événement. Les webhooks permettent une intégration en temps réel et asynchrone entre systèmes, sans interrogation constante.

Pour la facturation d’abonnements, ils sont indispensables : les passerelles préviennent votre boutique quand des prélèvements aboutissent, échouent ou sont remboursés, et beaucoup de ces événements se produisent en dehors de toute action d’un utilisateur (renouvellements, nouvelles tentatives, décisions bancaires asynchrones).

Pourquoi c’est important pour les boutiques WooCommerce

Sans webhooks, l’état de vos abonnements se désynchronise de celui de la passerelle de paiement. Un prélèvement de renouvellement aboutit à 2 h 00 du matin, mais votre boutique ne le sait que le lendemain, quand vous consultez à la main le tableau de bord de la passerelle.

La carte d’un client est mise à jour via l’espace libre-service de la passerelle, mais votre boutique affiche toujours l’ancienne. Les webhooks rendent tout cela automatique et instantané.

Pour les boutiques d’abonnement WooCommerce, des webhooks bien configurés font la différence entre une facturation automatisée et des cauchemars de rapprochement manuel. Des webhooks mal configurés causent les bugs d’abonnement les plus courants : des échecs silencieux où la passerelle a prélevé mais où votre boutique ne le reflète pas.

Comment ça fonctionne

Vous enregistrez une URL de webhook dans le tableau de bord de votre passerelle (par exemple votresite.com/wc-api/wc_stripe). Quand un événement survient côté passerelle (payment_intent.succeeded, customer.subscription.updated), la passerelle envoie un HTTP POST à votre URL avec une charge utile JSON décrivant l’événement.

Votre boutique vérifie la signature de la requête (preuve qu’elle vient bien de la passerelle et pas d’un acteur malveillant), traite l’événement (prolonge l’abonnement, envoie un e-mail, met à jour la base de données) et renvoie 200 OK. Si la passerelle reçoit une erreur ou aucune réponse, elle réessaie avec un délai croissant pendant des heures ou des jours.

Exemple concret

Un renouvellement d’abonnement Stripe se déclenche le vendredi à 2 h 00. Stripe traite le prélèvement de 39 $ : succès.

Stripe envoie un webhook `invoice.payment_succeeded` à `https://store.com/wc-api/wc_stripe` avec une charge utile contenant l’identifiant de l’abonnement, le montant et l’horodatage. WPSubscription le reçoit, vérifie la signature avec le secret de webhook Stripe, prolonge l’abonnement de 30 jours, crée une commande de renouvellement dans WooCommerce et met en file d’attente un e-mail de reçu.

Le client se réveille le vendredi matin avec un reçu, grâce au webhook déclenché pendant son sommeil.

Bonnes pratiques

  • Vérifiez toujours les signatures des webhooks : traiter des webhooks non signés est une faille de sécurité
  • Rendez vos gestionnaires de webhook idempotents : recevoir deux fois le même événement doit être sans risque
  • Répondez en moins de 5 secondes : des gestionnaires trop longs provoquent des délais dépassés et des nouvelles tentatives
  • Journalisez chaque webhook pour le débogage : les nouvelles tentatives de la passerelle peuvent masquer des problèmes
  • Utilisez les événements de test des tableaux de bord de passerelle pour vérifier l’intégration

Erreurs courantes

  • Ne pas vérifier les signatures des webhooks : un risque de sécurité et une source de bugs d’intégration
  • Des gestionnaires de webhook trop longs qui dépassent le délai : les passerelles réessaient, ce qui crée des traitements en double
  • Ne pas gérer les événements renvoyés : un webhook peut se déclencher plusieurs fois pour le même événement
  • Figer des URL de webhook de production en mode test : les événements partent vers le mauvais environnement
  • Ignorer les échecs de livraison de webhooks dans les tableaux de bord des passerelles : les échecs silencieux détruisent l’intégrité des données

Dans WooCommerce avec WPSubscription

WPSubscription reçoit les webhooks des passerelles sur des points d’accès WooCommerce standardisés (/wc-api/wc_stripe, /wc-api/wc_paypal, etc.). Le plugin gère automatiquement la vérification des signatures, le traitement des événements et la logique de nouvelles tentatives pour chaque passerelle prise en charge.

Des webhooks mal configurés sont la première source de bugs d’abonnement : vérifiez toujours la configuration des webhooks lors de l’intégration initiale de la passerelle.

Questions fréquentes

Pourquoi mes renouvellements d’abonnement fonctionnent-ils mais pas les e-mails ?
Il s’agit généralement d’un problème de configuration des webhooks. Le prélèvement de renouvellement aboutit côté passerelle (Stripe le gère de façon autonome), mais votre boutique ne reçoit pas le webhook de succès : la logique d’envoi d’e-mail ne se déclenche donc jamais. Vérifiez la livraison des webhooks dans le tableau de bord de votre passerelle pour repérer les livraisons échouées.
Comment tester les webhooks pendant le développement ?
Utilisez la fonction de test de webhooks de la passerelle (Stripe CLI, tableau de bord des webhooks PayPal) pour envoyer des événements de test à votre environnement local. Pour un test proche de la production, utilisez un service de tunnel comme ngrok pour exposer votre serveur local aux livraisons de webhooks. WPSubscription fonctionne avec tous les outils de test de webhooks standards.
Que se passe-t-il si mon serveur est hors service quand un webhook se déclenche ?
Les passerelles réessaient les livraisons échouées selon un calendrier croissant (en général 1 minute, 5 minutes, 30 minutes, 1 heure, etc.) pendant 3 à 7 jours, puis abandonnent. C’est pourquoi le suivi de la livraison des webhooks est essentiel : une longue indisponibilité peut entraîner des événements définitivement manqués qui désynchronisent l’état de vos abonnements.
Comment vérifier les signatures des webhooks ?
Chaque passerelle fournit un secret de signature de webhook dans son tableau de bord. Votre gestionnaire doit reconstituer la signature attendue à partir du corps de la requête avec HMAC-SHA256 (ou équivalent) et ce secret, puis la comparer à la signature de l’en-tête de la requête. WPSubscription le fait automatiquement pour les passerelles prises en charge.
Chaque événement de la passerelle doit-il avoir un gestionnaire de webhook ?
Configurez des webhooks pour les événements sur lesquels votre boutique doit agir : abonnement créé, mis à jour, supprimé, paiement réussi, paiement échoué, facture payée, remboursement émis, litige ouvert. Évitez de configurer des webhooks pour des événements que vous ignorez : moins de webhooks, c’est moins de points de défaillance et de meilleures performances.

Le plugin d’abonnements WooCommerce de référence dans le monde

Vendez des abonnements dès aujourd’hui.

Choisissez une formule, installez WPSubscription sur la boutique WooCommerce que vous gérez déjà et commencez à encaisser des revenus récurrents.

Voir les formules et tarifs