Les webhooks sont la manière la plus simple de réagir à une signature : dès qu'un événement se produit, la plateforme appelle une URL de votre application. Simple en apparence. En production, il faut compter avec les réseaux qui tombent, les serveurs qui redémarrent et les appels qui arrivent deux fois.
1. Ne pas croire un appel sur parole
N'importe qui peut envoyer une requête à votre URL. Chez Validature, les appels ne sont pas signés : la sécurité repose sur trois réflexes simples.
- une URL HTTPS longue et imprévisible, propre à chaque abonnement, gardée comme un mot de passe ;
- un appel reçu est une notification, pas une preuve : avant une décision importante (facturer, archiver), relisez la demande par l'API avec son identifiant ;
- les événements inconnus ou mal formés sont ignorés, sans erreur.
2. Répondre vite, traiter ensuite
Répondez immédiatement par un code 2xx, puis traitez l'événement de manière asynchrone (file de messages, tâche en arrière-plan). Une réponse lente est interprétée comme un échec et déclenche des rejeux.
Un webhook doit être acquitté en millisecondes et traité en arrière-plan.
3. Être idempotent
En cas de doute sur la réception, la plateforme rejoue l'appel. Vous recevrez donc parfois le même événement deux fois. Stockez l'identifiant unique de chaque événement (chez Validature, il accompagne aussi chaque livraison, dans l'en-tête X-Validature-Delivery-Id) et ignorez ceux déjà traités. Sans cette précaution, un même contrat peut créer deux factures.
4. Ne pas se fier à l'ordre d'arrivée
Les événements participant.signed et request.completed peuvent arriver dans le désordre. Fiez-vous à l'horodatage de l'événement, ou, mieux, interrogez l'API pour obtenir l'état à jour de la demande avant d'agir sur une étape critique.
5. Prévoir la reprise
Votre serveur a été indisponible ? Validature retente l'envoi jusqu'à six fois, avec un délai croissant à partir de 30 secondes ; une réponse 404 ou 410 met fin à l'abonnement. Au-delà, les derniers événements restent consultables par l'API. Prévoyez aussi une réconciliation périodique : une tâche quotidienne qui compare l'état des demandes via l'API avec votre base.
6. Ne pas stocker plus que nécessaire
Un webhook contient des identifiants et des statuts, rarement le document. Si vous téléchargez les documents signés, faites-le depuis l'API, avec une clé aux droits limités, et appliquez vos propres règles de conservation.
Les événements essentiels
| Événement | Usage typique |
|---|---|
request.sent | Mettre à jour le statut dans le CRM |
participant.viewed | Alerter le commercial |
participant.signed | Suivre la progression |
participant.declined | Prévenir le responsable du dossier |
request.completed | Archiver, facturer, déclencher la suite |
request.expired / request.canceled | Relancer ou clôturer l'opportunité |
Les demandes chiffrées (Vault) ne déclenchent aucun webhook : leur contenu reste lisible par leurs seuls destinataires. La référence complète est sur notre page développeurs.
Cet article est informatif et ne constitue pas un conseil juridique personnalisé. Pour une situation particulière, rapprochez-vous d'un professionnel du droit.
