Webhook - Webhook (Notification HTTP Inversée Basée sur les Événements)

Par Jeff Lindsay · 2007 · Sources officielles vérifiées

Architecture & APIsDonnée vérifiée & sourcéeArchitectureAPIÉvénementsHTTPSécuritéStripe

En résumé

Mécanisme de communication asynchrone permettant à une application d'envoyer automatiquement des données en temps réel à une autre application via une requête HTTP POST dès qu'un événement survient.

1. Définition détaillée & Contexte d'émergence

Souvent qualifié d''API inversée' ou de 'reverse API', un webhook fonctionne selon un modèle push plutôt que pull. Au lieu que votre application demande périodiquement 'y a-t-il un nouveau paiement ?', le fournisseur (Stripe, GitHub, Shopify) effectue un appel HTTP POST vers une URL publique sécurisée de votre serveur dès que l'événement `payment_intent.succeeded` se produit, transmettant les données au format JSON.

Pourquoi ce concept a été créé : Inventé pour remplacer le sondage permanent ('polling') inefficace, où un client interrogeait un serveur toutes les 5 secondes pour savoir si une nouvelle donnée était disponible.

2. Sécurisation et Traitement d’un Webhook

Traiter un webhook exige de vérifier scrupuleusement l'origine du message et de gérer les réessais en cas de panne.

1. Signature Cryptographique (HMAC SHA-256)

Le fournisseur signe le payload brut avec une clé secrète partagée transmise dans les en-têtes (ex: `stripe-signature`). Le serveur récepteur recalcule la signature pour garantir l'authenticité et l'intégrité.

2. Idempotence

En cas de timeout réseau, le fournisseur réémet le webhook plusieurs fois. Le serveur doit enregistrer l'ID de l'événement pour ne jamais traiter deux fois la même opération (ex: ne pas débiter deux fois un client).

3. Acquittement Rapide (Status 200 OK)

Renvoyer immédiatement un statut HTTP 200 et déléguer les traitements longs à une file de tâches en arrière-plan pour éviter les timeouts côté émetteur.

3. Caractéristiques fondamentales

  • Communication temps réel déclenchée par les événements.
  • Économie massive de requêtes et de bande passante par rapport au polling.
  • Gestion automatique des réessais avec backoff exponentiel par les fournisseurs.

5. Avantages et limites techniques

Points forts

  • ✓Mises à jour instantanées des systèmes.
  • ✓Norme universelle supportée par tous les grands services mondiaux (Stripe, GitHub, Slack, Twilio).

Points de vigilance

  • ⚠Nécessite que votre endpoint soit accessible publiquement sur Internet (usage de ngrok ou Localtunnel en développement local).
  • ⚠Vulnérabilité aux attaques par rejeu si la signature et le timestamp ne sont pas vérifiés.

6. Recommandations : Quand l'utiliser ?

Idéal pour :

  • Réception de paiements (Stripe), synchronisation de statuts e-commerce, déploiements CI/CD sur push Git.

À éviter pour :

  • Transfert continu de données à très haute fréquence (ex: flux télémétriques temps réel, préférer Kafka ou WebSockets).

8. Sources officielles vérifiées

Données techniques vérifiées auprès des documentations officielles, des RFCs et des spécifications standards.

W3C WebSub Recommendation (Architecture de Webhooks Pub/Sub)World Wide Web Consortium (W3C)