Un webhook, c'est quoi ? Quand c'est le service qui vous prévient

Un webhook est un message qu'un service envoie automatiquement à votre application dès qu'un événement se produit, par exemple un paiement réussi. C'est le service qui vous prévient, au lieu que vous alliez lui demander.

L'analogie : la sonnette

Vous attendez un colis. Première méthode : descendre vérifier la boîte aux lettres toutes les cinq minutes. Deuxième méthode : le livreur sonne quand il arrive.

La première s'appelle le sondage (polling) : vous interrogez sans cesse, et le plus souvent la réponse est « rien de nouveau ». La seconde, c'est le webhook : le service appelle une adresse que vous lui avez indiquée, au bon moment.

Comment ça marche

1. Vous donnez au service l'adresse (une URL) de votre application.
2. Un événement a lieu chez lui : paiement confirmé, formulaire reçu, message livré…
3. Il envoie une requête à votre adresse avec les détails de l'événement.
4. Votre application répond « bien reçu », puis fait le travail.

C'est le fonctionnement d'une API, mais à l'envers : ici, c'est le service qui vous appelle.

Les pièges à connaître

• Les doublons. Si votre réponse tarde ou échoue, le service réessaie, et le même événement peut arriver deux fois. Votre code doit pouvoir le traiter deux fois sans effet double : c'est l'idempotence.
• Le désordre. Les messages n'arrivent pas toujours dans l'ordre où les événements se sont produits.
• Les messages falsifiés. Votre adresse est publique : n'importe qui peut lui envoyer un message qui prétend venir du service.
• La lenteur. Si votre application met trop de temps à répondre, le service peut considérer l'envoi comme raté.

Les bons réflexes

• Vérifier la signature. Le service signe en général chaque message avec un secret partagé. Vérifiez-la avant de faire confiance au contenu, et gardez ce secret hors du code envoyé au navigateur.
• Répondre vite, puis traiter en arrière-plan avec une file d'attente.
• Garder une trace des événements reçus et de leur traitement.
• Gérer les doublons en retenant l'identifiant de chaque événement.

Un exemple concret

Prenons une boutique en ligne (exemple illustratif). Quand un client paie, le service de paiement envoie un webhook à la boutique pour confirmer. La boutique marque alors la commande comme payée et prépare l'envoi. Sans cela, elle devrait demander sans cesse au service « cette commande est-elle payée ? », ou pire, se fier à la page que le client voit à l'écran, qu'il peut fermer avant la fin.

À retenir

Un webhook, c'est une sonnette plutôt qu'une vérification permanente. Il faut vérifier qui sonne, et prévoir qu'on puisse sonner deux fois.

Et pour votre produit ?

Les paiements et les notifications reposent souvent sur des webhooks, et c'est là que se cachent des erreurs coûteuses : une commande comptée deux fois, un message falsifié accepté. Un audit de votre application examine ces points. On peut en parler lors d'un échange de 30 minutes.