Webhooks de signature électronique : HMAC, rejeu, ordre et SSRF
Un webhook fiable doit être authentifié, rejouable et résistant aux doublons, au désordre et aux URL malveillantes.
Les webhooks relient la signature aux CRM, ERP et systèmes documentaires. Ils concentrent aussi des risques : faux événement de finalisation, secret exposé, rejeu, traitement deux fois d’une facture ou utilisation du serveur comme proxy vers un réseau interne.
La sécurité ne repose pas seulement sur une signature HMAC. Elle combine format canonique, fenêtre temporelle, identifiant unique, règles réseau, observabilité et modèle de livraison explicite.
Signer et vérifier correctement
Calculez un HMAC avec un algorithme moderne sur le timestamp et les octets exacts du corps. Le récepteur doit lire le corps brut, recalculer la valeur et utiliser une comparaison en temps constant. Refusez les timestamps hors fenêtre, tout en tenant compte d’une dérive raisonnable.
Versionnez l’en-tête de signature pour permettre la rotation d’algorithme. Pendant une rotation de secret, acceptez temporairement ancien et nouveau, puis retirez l’ancien avec une date contrôlée. Ne journalisez jamais le secret ni la valeur complète des données sensibles.
Traiter doublons et désordre
Chaque événement doit avoir un identifiant stable. Enregistrez-le avant d’appliquer l’effet métier, dans la même transaction logique lorsque possible. Un accusé 2xx signifie que l’événement est durablement pris en charge, pas nécessairement que tout le traitement aval est terminé.
Ne déduisez pas l’état final de l’ordre d’arrivée. Comparez version, séquence ou état récupéré depuis l’API. Un événement completed reçu avant signer.signed ne doit pas faire régresser le dossier lors de la livraison tardive du second.
Empêcher le webhook de devenir un SSRF
Validez les URL HTTPS, résolvez et bloquez les plages privées, loopback, link-local et métadonnées cloud. Revalidez après redirection et limitez le nombre de redirections. Protégez-vous aussi contre le DNS rebinding.
Isolez le worker de livraison, appliquez des timeouts, une taille maximale de réponse et un egress réseau restreint. Les journaux doivent afficher le résultat sans stocker les payloads complets contenant des données personnelles.
Grille de décision
| Risque | Contrôle émetteur | Contrôle récepteur |
|---|---|---|
| Faux événement | HMAC versionné | Vérification du corps brut |
| Rejeu | Identifiant et timestamp | Fenêtre et table de déduplication |
| Désordre | Séquence ou version | Machine d’état monotone |
| SSRF | Validation et egress | Sans objet pour la réception |
| Panne | Retry exponentiel | File durable et réconciliation |
Plan d’action
- Signer timestamp et corps brut
- Comparer en temps constant
- Dédupliquer par identifiant
- Rendre les effets idempotents
- Bloquer IP privées et redirections
- Fournir historique et rejeu contrôlé
Questions fréquentes
Faut-il chiffrer le payload ?
TLS protège le transport. Un chiffrement applicatif peut être ajouté selon la sensibilité, mais ne remplace pas l’authentification et l’intégrité.
Combien de temps rejouer ?
Définissez une politique documentée avec backoff et file d’échec, puis permettez un rejeu manuel audité.
Pourquoi la SSRF concerne-t-elle l’émetteur ?
Parce qu’il effectue une requête vers une URL fournie par le client, potentiellement dirigée vers une ressource interne.
Sources officielles et techniques
Important
Ce contenu fournit une information générale et ne remplace pas un avis juridique ou un audit de conformité. Le niveau de signature adapté dépend du contexte, de l’identification, de l’authentification et des preuves effectivement produites.