Webhooks de signature : automatiser et sécuriser la post-signature

Ce qu'il faut retenir

Les webhooks sont le mécanisme standard pour déclencher des actions après un événement de signature (signé, refusé, expiré).
Le traitement des webhooks doit être idempotent : un même événement peut être livré plusieurs fois.
Il faut vérifier la signature du webhook pour s'assurer qu'il provient bien du prestataire de signature.
Les échecs de livraison doivent être retentés avec une file d'attente, pas traités en direct.

Une fois les documents signés, les systèmes métier doivent être informés : mettre à jour le CRM, déclencher un paiement, notifier un conseiller. Les webhooks sont le moyen fiable de transmettre ces événements post-signature. Cet article détaille comment les recevoir, les sécuriser et les traiter correctement.

Pourquoi des webhooks pour la post-signature

Le cycle d'un document ne s'arrête pas à la signature :

statut signé → mise à jour du dossier ;
statut refusé → relance, étape de médiation ;
statut expiré → renvoi, nouveau cycle ;
chaque événement peut déclencher des actions métier.

Plutôt que de scruter périodiquement l'API (polling), le webhook pousse l'événement vers votre serveur dès qu'il survient. C'est plus rapide, plus simple et réduit la charge.

Architecture recommandée pour les recevoir

Endpoint dédié : une route /webhooks/signature qui reçoit les événements.
Vérification de la signature : chaque appel doit être authentifié (en-tête HMAC ou JWT signé).
Acquittement rapide : répondre 200 OK le plus vite possible, sans traitement long.
File d'attente : mettre l'événement en file et le traiter en arrière-plan.
Idempotence : pouvoir traiter deux fois le même événement sans effet double.

L'erreur classique est de traiter le webhook dans la requête elle-même : un traitement long ralentit la réponse et provoque des retries du prestataire.

Sécuriser le webhook : vérifier son origine

Un endpoint de webhook exposé sur Internet peut recevoir des appels malveillants. Il faut vérifier :

la signature HMAC calculée sur le corps de la requête avec une clé secrète partagée ;
l'horodatage de l'en-tête pour limiter les rejeux ;
l'utilisation du HTTPS pour protéger le corps en transit.

La clé HMAC ne doit jamais être exposée côté client ni loggée. En cas d'échec de vérification, la requête est rejetée sans traitement.

L'idempotence : le réflexe indispensable

Les prestataires peuvent livrer un même événement plusieurs fois (retry après timeout, doublon réseau). Le traitement doit donc être idempotent :

stockez un identifiant unique d'événement ;
vérifiez s'il a déjà été traité avant d'exécuter l'action ;
répondez de manière identique en cas de doublon.

Sans idempotence, un événement « signé » reçu deux fois peut créer deux factures, deux relances ou deux envois d'email.

Gestion des échecs et retries

Une livraison de webhook peut échouer (serveur down, timeout, erreur applicative). Le traitement doit prévoir :

Situation	Comportement attendu
Réponse 2xx du webhook	Événement traité, aucune relivraison
Réponse 4xx (rejet)	Arrêt des retries : erreur permanente
Réponse 5xx ou timeout	Retry avec backoff exponentiel, puis file de secours
Doublon reçu	Détecté et ignoré grâce à l'idempotence

En cas d'échec durable, il faut pouvoir consulter l'historique des livraisons et relancer manuellement un traitement.

Quels événements traiter

document.signé : déclenche la mise à jour du dossier et les actions de suivi.
document.refusé : notifie, planifie une relance, déclenche le circuit d'exception.
document.expiré : renvoie, gère le cycle de relance.
document.consulté : trace la lecture, utile pour la preuve.
document.signataire.ajouté : synchronise les changements d'équipe.

Le choix des événements dépend du besoin métier. Un minimum utile est : signé, refusé, expiré.

Erreurs fréquentes à éviter

Ne pas vérifier la signature du webhook : l'endpoint devient une porte d'entrée pour des données falsifiées.
Traiter l'événement dans la requête : réponse lente, retries en cascade.
Ignorer l'idempotence : doublons de facturation ou de relance.
Pas de suivi des échecs : des signatures jamais synchronisées.
Logger les clés secrètes : une fuite compromet l'authentification.

Checklist d'intégration de webhooks

Créer un endpoint dédié, protégé par vérification de signature.
Acquitter immédiatement (2xx) et traiter en file.
Garantir l'idempotence par identifiant d'événement.
Configurer le retry et la relance manuelle des échecs.
Tester : double livraison, timeout, événement malformé.
Surveiller les erreurs avec des alertes.

Pour aller plus loin

Intégrer la signature électronique à votre CRM — les mêmes principes appliqués à l'intégration CRM.
Intégrer une API de signature électronique — architecture et bonnes pratiques (programmé).
Sécuriser vos webhooks de signature — approfondissement sécurité (programmé).

Questions fréquentes

Que faire si je reçois un doublon ?

Utiliser l'identifiant d'événement pour vérifier si le traitement a déjà eu lieu. Répondre sans refaire l'action.

Faut-il utiliser le polling en plus des webhooks ?

Un rapprochement périodique est une bonne pratique de surveillance, mais il ne remplace pas les webhooks pour la réactivité.

Comment protéger mon endpoint ?

HTTPS, vérification HMAC, validation de l'horodatage, pas de log de secrets.

Sources officielles

Pour aller plus loin

La fiabilité de votre intégration dépend de la gestion des retries et de l'idempotence. Le détail de l'architecture d'intégration est présenté dans l'article dédié aux APIs de signature.

Ce contenu fournit une information technique générale. Les contrats de service des prestataires de signature définissent les garanties de livraison applicables.