Webhooks expliqués : charges utiles signées et nouvelles tentatives pour des intégrations fiables
Vous venez de créer un point de terminaison pour recevoir des webhooks d'un fournisseur de paiement. Le premier test fonctionne bien, mais en production, vous remarquez des événements manquants, des doublons de facturation et aucun moyen de savoir si une requête est authentique. Les webhooks sont simples en théorie mais délicats à bien mettre en œuvre. Ce guide explique comment sécuriser les webhooks avec des charges utiles signées et implémenter une logique de nouvelles tentatives robuste pour que vos intégrations ne échouent pas silencieusement.
Que sont les webhooks et pourquoi ils importent
Les webhooks sont des callbacks HTTP définis par l'utilisateur, déclenchés par des événements. Au lieu que votre application interroge une API pour détecter des changements, le service pousse les données vers votre point de terminaison lorsqu'un événement se produit. Cela rend les intégrations efficaces et quasi temps réel.
Les cas d'utilisation courants incluent les notifications de paiement (par exemple Stripe), les déclencheurs CI/CD (par exemple GitHub) et les plateformes de messagerie (par exemple Slack). Mais avec ce modèle push, vous perdez le contrôle sur le moment où les requêtes arrivent. C'est pourquoi vous devez gérer explicitement la sécurité et la fiabilité.
Le problème de sécurité : les webhooks non signés sont dangereux
Un webhook non signé n'est qu'un POST HTTP vers une URL publique. N'importe qui peut envoyer une requête qui semble provenir de votre fournisseur de paiement. Sans vérification, des attaquants pourraient forger des événements, entraînant des commandes frauduleuses, des fuites de données ou des actions non autorisées.
La solution consiste à signer la charge utile. L'expéditeur calcule une signature cryptographique sur le corps de la requête à l'aide d'un secret partagé, et l'inclut dans un en-tête. Votre point de terminaison recalcule la signature et la compare. Si elles correspondent, vous savez que la requête est authentique et n'a pas été altérée.
Comment signer les charges utiles de webhook avec HMAC
HMAC (Hash-based Message Authentication Code) est la norme pour la signature de webhooks. Il utilise une clé secrète et une fonction de hachage (comme SHA-256) pour produire une signature unique à la charge utile et au secret.
Voici comment un expéditeur pourrait signer une charge utile en Python :
import hmac
import hashlib
import json
secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature:
Côté réception, vous devez vérifier la signature avant de traiter la charge utile :
import hmac
import hashlib
def verify_signature(payload, received_signature, secret):
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)
Important : Utilisez toujours une fonction de comparaison à temps constant comme hmac.compare_digest pour éviter les attaques temporelles. Vérifiez également la signature par rapport au corps brut de la requête, et non à une version analysée, car la sérialisation JSON peut différer.
Bonnes pratiques pour les charges utiles signées
- Utilisez un secret fort : Générez un secret aléatoire d'au moins 32 octets et stockez-le en lieu sûr (par exemple, variable d'environnement ou gestionnaire de secrets).
- Incluez un horodatage : Ajoutez un horodatage à la charge utile signée et rejetez les requêtes datant de plus de quelques minutes pour prévenir les attaques par rejeu.
- Utilisez HTTPS : Transmettez toujours les webhooks via TLS pour protéger la charge utile et la signature en transit.
- Faites tourner les secrets périodiquement : Prenez en charge plusieurs secrets actifs pendant la rotation pour éviter les interruptions de service.
Gérer les échecs : nouvelles tentatives et idempotence
Les webhooks peuvent échouer : votre serveur peut être indisponible, le réseau peut tomber, ou votre point de terminaison peut renvoyer une erreur. Un expéditeur fiable réessaiera la livraison, mais vous devez concevoir votre récepteur pour gérer les doublons et les événements désordonnés.
Stratégies de nouvelle tentative
La plupart des fournisseurs de webhooks utilisent un backoff exponentiel avec gigue. Par exemple, réessayez après 1 minute, puis 5 minutes, puis 30 minutes, jusqu'à un nombre maximal de tentatives. Cela donne à votre système le temps de récupérer sans le surcharger.
Si vous construisez le côté expéditeur, implémentez une file d'attente avec des nouvelles tentatives planifiées. Stockez la charge utile et le nombre de tentatives, et utilisez un worker pour traiter les nouvelles tentatives.
Idempotence : la clé de nouvelles tentatives sûres
Parce que les nouvelles tentatives peuvent entraîner des livraisons en double, votre point de terminaison doit être idempotent. Cela signifie que traiter le même événement plusieurs fois doit avoir le même effet que le traiter une seule fois.
Approches courantes :
- Utilisez un ID d'événement unique : Incluez un ID dans la charge utile et stockez les ID traités dans une base de données. Ignorez les événements dont les ID ont déjà été vus.
- Concevez des opérations idempotentes : Par exemple, utilisez des upserts au lieu d'insertions, ou vérifiez si une ressource existe déjà avant de la créer.
Voici une simple vérification d'idempotence en Python :
def process_event(event_id, payload):
if db.exists('processed_events', event_id):
return # already processed
# process payload
db.insert('processed_events', event_id)
Assurez-vous que la vérification et le traitement se produisent dans une seule transaction pour éviter les conditions de course.
Comparaison : polling vs webhooks
| Aspect | Polling | Webhooks |
|---|---|---|
| Latence | Dépend de l'intervalle (par exemple 5 min) | Quasi temps réel |
| Charge serveur | Requêtes constantes même sans changement | Requêtes uniquement sur événements |
| Complexité | Simple à implémenter | Nécessite signature, nouvelles tentatives, idempotence |
| Fiabilité | Vous contrôlez les nouvelles tentatives | Dépend de la politique de nouvelle tentative de l'expéditeur |
Étape par étape : implémenter un récepteur de webhook sécurisé
- Configurez un point de terminaison HTTPS qui accepte les requêtes POST et lit le corps brut.
- Extrayez l'en-tête de signature (par exemple
X-Signature) et l'en-tête d'horodatage s'il est présent. - Vérifiez la signature à l'aide de HMAC et de votre secret. Rejetez si elle est invalide.
- Vérifiez l'horodatage pour prévenir les attaques par rejeu (par exemple, rejetez si plus ancien que 5 minutes).
- Analysez la charge utile et extrayez l'ID de l'événement.
- Vérifiez l'idempotence en recherchant l'ID de l'événement dans votre base de données.
- Traitez l'événement dans une transaction qui enregistre également l'ID de l'événement.
- Retournez un statut 2xx rapidement pour accuser réception. Si le traitement prend du temps, mettez la tâche en file d'attente et retournez 202 Accepted.
Tester votre implémentation de webhook
Utilisez des outils comme ngrok pour exposer votre serveur local et simuler des webhooks. Écrivez des tests unitaires pour la vérification de signature, l'idempotence et la logique de nouvelle tentative. Par exemple, testez qu'un ID d'événement en double est ignoré et qu'une signature invalide renvoie 401.
Lors du débogage, journalisez la charge utile reçue et la signature (mais ne journalisez jamais les secrets). Si vous travaillez avec des charges utiles JSON, un formateur JSON peut vous aider à inspecter et valider la structure rapidement.
FAQ
Qu'est-ce qu'une charge utile de webhook signée ?
Une charge utile signée inclut une signature cryptographique (généralement HMAC) calculée sur le corps de la requête avec un secret partagé. Le récepteur vérifie la signature pour s'assurer que la requête est authentique et non altérée.
Combien de fois un webhook doit-il être réessayé ?
Il n'y a pas de nombre universel, mais la pratique courante est de 3 à 5 nouvelles tentatives avec backoff exponentiel. Au-delà, l'événement est souvent marqué comme échoué et peut nécessiter une intervention manuelle ou une file d'attente de lettres mortes.
Puis-je utiliser des webhooks sans HTTPS ?
Vous ne devriez jamais utiliser de webhooks sur HTTP simple. Sans TLS, les attaquants peuvent intercepter la charge utile et la signature, et rejouer ou modifier les requêtes. Utilisez toujours HTTPS.
Prêt à inspecter et formater les charges utiles de webhook ? Essayez notre formateur JSON gratuit pour valider et embellir les données JSON instantanément.