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.
Guides pratiques associés
Comment intégrer Stripe aux abonnements WooCommerce
Connectez Stripe à WPSubscription pour une facturation récurrente fiable, des webhooks et la récupération des paiements.
Comment configurer les abonnements PayPal dans WooCommerce
Activez la facturation récurrente PayPal pour vos abonnements WooCommerce avec WPSubscription.
