Qu'est-ce qu'un webhook ? Comment les applications se notifient entre elles

Un webhook est un message automatique qu'un service envoie à votre application au moment précis où quelque chose se produit. Quand le paiement d'un client réussit, Stripe envoie un webhook à une adresse de votre application indiquant « paiement réussi, voici les détails », et votre application réagit — marque la commande comme payée, envoie un reçu, débloque le compte. En bref : une API, c'est votre application qui pose une question à un autre service ; un webhook, c'est l'autre service qui appelle votre application pour lui signaler quelque chose.

Pourquoi c'est important quand on crée avec l'IA

Dès que votre application encaisse des paiements, reçoit des formulaires envoyés par un autre outil, ou se connecte à des services comme GitHub, Shopify ou un calendrier, vous rencontrerez les webhooks. Ce sont généralement la manière correcte de savoir qu'un événement s'est produit — mais c'est aussi là que les applications créées avec l'IA se trompent le plus souvent, de façon subtile :

• Le point d'accès accepte n'importe quelle requête, donc n'importe qui peut simuler un événement « paiement réussi ».
• L'application donne l'accès sur la page de retour du paiement au lieu de le faire via le webhook : les personnes qui ferment l'onglet trop tôt n'obtiennent jamais ce qu'elles ont payé, et celles qui trouvent l'URL de succès l'obtiennent gratuitement.
• Le même événement arrive deux fois et le client reçoit deux commandes ou deux e-mails.

Comprendre le fonctionnement des webhooks vous permet de demander les protections nécessaires dès le départ.

Une analogie du quotidien : le SMS de livraison

Vous pouvez savoir si votre colis est arrivé de deux façons. Vous pouvez aller regarder la porte d'entrée toutes les dix minutes (c'est l'interrogation — votre application appelle sans cesse une API pour demander « quelque chose de nouveau ? »). Ou le livreur peut vous envoyer un SMS dès la livraison (c'est un webhook).

Le SMS est nettement préférable — à condition de pouvoir lui faire confiance. Si n'importe qui pouvait vous envoyer un message « colis livré », vous voudriez pouvoir vérifier qu'il vient bien du livreur. Et si votre téléphone était éteint au moment de l'envoi, vous voudriez que le livreur réessaie plus tard. Ces deux préoccupations — la vérification et les nouvelles tentatives — constituent l'essentiel de la difficulté des webhooks.

Comment fonctionne un webhook, étape par étape

1. Vous créez un point d'accès dans le backend de votre application : une URL comme https://yourapp.com/webhooks/stripe qui accepte les requêtes POST.
2. Vous enregistrez cette URL auprès du prestataire et choisissez les événements souhaités (par exemple « paiement de commande terminé » et « abonnement résilié »).
3. Le prestataire vous fournit un secret de signature. Vous le stockez comme secret sur votre serveur — voir variables d'environnement et secrets.
4. Un événement se produit. Le prestataire envoie une requête HTTP à votre URL, avec un corps JSON qui décrit l'événement, plus un en-tête de signature.
5. Votre application vérifie la signature, enregistre l'identifiant de l'événement, répond rapidement avec un code de succès (200), puis effectue le traitement.
6. Si votre application ne répond pas avec un succès, beaucoup de prestataires réessaient plus tard.

Signatures

Une signature prouve que la requête vient bien du prestataire et n'a pas été modifiée. Stripe, par exemple, calcule un HMAC (une sorte d'empreinte à clé) en SHA-256 sur le corps de la requête et un horodatage, à l'aide du secret de signature, et l'envoie dans un en-tête Stripe-Signature. Votre application fait le même calcul avec sa copie du secret ; si les résultats correspondent, la requête est authentique. Comme l'horodatage est aussi signé, vous pouvez rejeter les anciennes requêtes qu'un tiers aurait enregistrées pour les rejouer plus tard — les bibliothèques de Stripe utilisent par défaut une tolérance de cinq minutes, selon sa documentation à la date de septembre 2026.

Un détail pratique : la signature est calculée sur le corps brut de la requête. Si votre framework analyse et reformate le JSON avant la vérification, le contrôle échoue. C'est un bogue très courant.

Nouvelles tentatives, doublons et ordre

Les prestataires diffèrent, vérifiez donc la documentation de chacun. À la date de septembre 2026 :

La documentation de Stripe indique également que les événements ne sont pas garantis d'arriver dans l'ordre où ils se sont produits, et que le même événement peut parfois arriver plus d'une fois ; elle recommande donc de suivre les identifiants d'événements.

La leçon générale vaut pour tout prestataire : les événements peuvent arriver en retard, plusieurs fois et dans le désordre. Votre gestionnaire doit être idempotent — traiter deux fois le même événement a le même effet que le traiter une seule fois.

Exemple concret : débloquer un cours payant

Vous vendez un cours en ligne. Un étudiant clique sur Acheter, paie sur la page de paiement hébergée par Stripe, et revient sur votre site.

La méthode fragile : la page de « merci » débloque le cours. Si l'étudiant ferme son navigateur pendant la redirection, il a payé mais n'a pas d'accès. Si quelqu'un devine l'URL de la page de remerciement, il obtient l'accès sans payer.

La méthode par webhook :

1. Lorsque Stripe confirme le paiement, il envoie un événement checkout.session.completed à /webhooks/stripe.
2. Votre backend vérifie la signature avec le secret de signature. Si elle échoue, il répond 400 et ne fait rien d'autre.
3. Il vérifie si cet identifiant d'événement a déjà été traité. Si oui, il répond 200 et s'arrête.
4. Il enregistre l'identifiant de l'événement, répond 200, puis accorde l'accès à l'étudiant et envoie un e-mail de bienvenue.
5. La page de remerciement indique simplement « Paiement reçu — votre cours apparaîtra dans un instant » et vérifie le statut d'accès de l'étudiant.

Plus tard, si un abonnement est résilié ou qu'une carte est refusée, d'autres événements de webhook indiquent à votre application de retirer ou de suspendre l'accès. C'est ainsi que les produits par abonnement restent synchronisés avec la facturation — voir qu'est-ce que le SaaS et comment ajouter des paiements à votre application.

Termes clés

• Point d'accès (endpoint) : l'URL de votre application qui reçoit les webhooks.
• Événement / charge utile (payload) : ce qui s'est passé, et les données qui le décrivent (généralement du JSON).
• Secret de signature : le secret partagé utilisé pour vérifier les signatures.
• Idempotent : qui peut être exécuté plusieurs fois avec le même résultat.
• Interrogation (polling) : demander à répétition à une API s'il y a des changements, au lieu d'attendre un webhook.
• Tunnel : un outil qui donne à un ordinateur portable une URL publique temporaire pour que les webhooks puissent l'atteindre pendant le développement.

Erreurs fréquentes et idées reçues

• Ne pas vérifier les signatures. L'URL du point d'accès n'est pas un secret. C'est la vérification qui rend la requête fiable.
• Effectuer un travail lent avant de répondre. Envoyer des e-mails ou générer des PDF avant de répondre peut provoquer des délais d'attente, qui déclenchent de nouvelles tentatives, qui provoquent des doublons.
• Supposer une livraison unique et ordonnée. Enregistrez les identifiants d'événements et ne vous fiez pas à l'ordre d'arrivée.
• Utiliser une URL d'aperçu. Les webhooks ont besoin d'une adresse publique et stable. Les aperçus privés et localhost ne sont pas accessibles depuis Internet ; utilisez votre URL publiée (ou un tunnel pendant les tests).
• Mélanger les secrets de test et de production. Les prestataires délivrent souvent des secrets de signature différents pour le mode test et le mode production. Stockez les deux et utilisez le bon.
• Faire confiance aveuglément au contenu pour les décisions importantes. Pour les actions à fort enjeu, il est raisonnable de récupérer l'état le plus récent auprès de l'API du prestataire après avoir reçu l'événement.

Ce qu'il faut demander à votre créateur d'IA

Ajoute un point d'accès POST /webhooks/stripe sur le serveur. Vérifie la signature Stripe à partir du corps brut de la requête et du secret STRIPE_WEBHOOK_SECRET. Rejette les signatures invalides avec un 400. Enregistre l'identifiant de chaque événement et ignore les événements déjà traités. Réponds 200 rapidement, puis traite checkout.session.completed en marquant la commande comme payée et en envoyant le reçu. Journalise le type d'événement. N'accorde pas l'accès depuis la page de succès du paiement.

Testez ensuite : envoyez un événement de test depuis le tableau de bord du prestataire, renvoyez le même, puis envoyez une requête avec une mauvaise signature. Seul le premier doit modifier quoi que ce soit.

Les webhooks sur Mythex

Mythex ne fait pas tourner de service de webhooks séparé ; vous demandez à l'agent d'ajouter un point d'accès de webhook dans le backend de votre propre application, puis vous indiquez au prestataire votre URL publiée, car les webhooks ont besoin d'une adresse publique. Le secret de signature va dans les secrets de votre projet, et si vous le modifiez sur une application en ligne, vous republiez. La recette de la documentation sur la gestion des webhooks contient un prompt de départ, et les modèles de boutique sont un bon point de départ pour les applications qui encaissent des paiements.

Questions