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

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

Pourquoi c'est important quand on construit avec l'IA

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

• Le point d'entrée accepte n'importe quelle requête, donc n'importe qui peut simuler un événement « paiement réussi ».
• L'app donne accès sur la page de redirection après paiement plutôt que via le webhook; ainsi, 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 courriels.

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

Une analogie du quotidien : le texto de livraison

Vous pouvez savoir si votre colis est arrivé de deux façons. Vous pouvez marcher jusqu'à la porte d'entrée toutes les dix minutes pour vérifier (c'est le sondage — votre app qui appelle sans cesse une API pour demander « quoi de neuf? »). Ou le livreur peut vous envoyer un texto quand il livre (c'est un webhook).

Le texto est nettement préférable — tant que vous pouvez lui faire confiance. Si n'importe qui pouvait vous envoyer un message « colis livré », vous voudriez un moyen de savoir qu'il vient vraiment du livreur. Et si votre téléphone était éteint au moment du message, vous voudriez que le livreur réessaie plus tard. Ces deux préoccupations — la vérification et les nouvelles tentatives — sont l'essentiel de ce qui rend les webhooks délicats.

Comment fonctionne un webhook, étape par étape

1. Vous créez un point d'entrée dans le serveur de votre app : une URL comme https://votreapp.com/webhooks/stripe qui accepte les requêtes POST.
2. Vous enregistrez cette URL auprès du fournisseur et choisissez les événements voulus (par exemple « paiement terminé » et « abonnement annulé »).
3. Le fournisseur vous donne un secret de signature. Vous le stockez comme secret sur votre serveur — voir variables d'environnement et secrets.
4. Un événement survient. Le fournisseur envoie une requête HTTP à votre URL, avec un corps JSON qui décrit l'événement, ainsi qu'un en-tête de signature.
5. Votre app vérifie la signature, enregistre l'identifiant de l'événement, répond rapidement par un code de succès (200), puis effectue le travail.
6. Si votre app ne répond pas par un succès, beaucoup de fournisseurs réessaient plus tard.

Les signatures

Une signature prouve que la requête vient du fournisseur et qu'elle n'a pas été modifiée. Stripe, par exemple, calcule un HMAC (une sorte d'empreinte à clé) avec SHA-256 sur le corps de la requête et un horodatage, en utilisant le secret de signature, et l'envoie dans un en-tête Stripe-Signature. Votre app 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 ont une tolérance par défaut de cinq minutes, selon sa documentation en 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 fréquent.

Nouvelles tentatives, doublons et ordre

Les fournisseurs diffèrent; vérifiez la documentation de chacun. En date de septembre 2026 :

La documentation de Stripe indique aussi 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 fournisseur : les événements peuvent arriver en retard, plus d'une fois et dans le désordre. Votre gestionnaire devrait être idempotent — traiter le même événement deux fois a le même effet que le traiter une seule fois.

Un 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, puis revient sur votre site.

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

La méthode par webhook :

1. Quand Stripe confirme le paiement, il envoie un événement checkout.session.completed à /webhooks/stripe.
2. Votre serveur vérifie la signature avec le secret de signature. Si elle échoue, il répond 400 et ne fait rien.
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 courriel de bienvenue.
5. La page de remerciement dit 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 annulé ou qu'une carte est refusée, d'autres événements de webhook indiquent à votre app de retirer ou de suspendre l'accès. C'est ainsi que les produits par abonnement restent synchronisés avec la facturation — voir ce qu'est le SaaS et comment ajouter des paiements à votre app.

Termes clés

• Point d'entrée (endpoint) : l'URL de votre app qui reçoit les webhooks.
• Événement / charge utile (payload) : ce qui s'est produit, 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 : sûr à exécuter plus d'une fois avec le même résultat.
• Sondage (polling) : demander sans cesse à 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 courantes et idées reçues

• Ne pas vérifier les signatures. L'URL du point d'entrée n'est pas un secret. La vérification est ce qui rend la requête digne de confiance.
• Faire un travail lent avant de répondre. Envoyer des courriels ou générer des PDF avant de répondre peut causer des délais d'attente, qui déclenchent des nouvelles tentatives, qui causent des doublons.
• Supposer une livraison unique, dans l'ordre. 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 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 fournisseurs émettent souvent des secrets de signature différents pour les modes test et direct. Conservez les deux et utilisez le bon.
• Faire confiance aveuglément à la charge utile pour des décisions importantes. Pour les actions à fort enjeu, il est raisonnable de récupérer le dernier état auprès de l'API du fournisseur après avoir reçu l'événement.

Quoi demander à votre outil de création IA

Ajoute un point d'entrée 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 400. Enregistre chaque identifiant d'événement et ignore les événements déjà traités. Réponds 200 rapidement, puis traite checkout.session.completed en marquant la commande payée et en envoyant le reçu. Journalise le type d'événement. Ne donne pas l'accès depuis la page de succès du paiement.

Ensuite, testez : envoyez un événement de test depuis le tableau de bord du fournisseur, renvoyez le même, puis envoyez une requête avec une mauvaise signature. Seul le premier devrait rien modifier.

Les webhooks dans Mythex

Mythex n'exploite pas de service de webhooks séparé; vous demandez à l'agent d'ajouter un point d'entrée de webhook dans le serveur de votre propre app, puis vous indiquez au fournisseur votre URL publiée, puisque 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 app en ligne, vous publiez à nouveau. La recette de la documentation sur la gestion des webhooks contient une invite de départ, et les modèles de boutiques sont un bon point de départ pour les apps qui acceptent des paiements.

Questions