Configurer les webhooks¶

Introduction¶

Les webhooks permettent à votre application de recevoir des notifications en temps réel lorsque des événements se produisent dans VoidSign, comme la finalisation d'une demande de signature. Au lieu d'interroger l'API de manière répétée pour vérifier les changements de statut, VoidSign envoie une requête HTTP POST à votre endpoint dès qu'un événement se produit.

Les webhooks fonctionnent de manière identique pour les deux flux d'intégration (voidsign_mail et caller_embed).

VoidSign implémente la spécification Standard Webhooks v1 pour la signature des événements webhook.

Pourquoi les webhooks plutôt que le polling¶

• Le polling gaspille des requêtes : vérifier le statut toutes les quelques secondes consomme rapidement votre limite de débit, surtout avec plusieurs demandes simultanées.
• Le polling ajoute de la latence : vous ne détectez la finalisation qu'au prochain cycle de polling, pas à l'instant où elle se produit.
• Les webhooks sont instantanés : VoidSign envoie un événement à votre endpoint dès que tous les signataires ont signé.
• Les webhooks sont plus simples : pas besoin de construire et maintenir une boucle d'interrogation, de gérer les intervalles ou de traiter les cas limites liés à la synchronisation.

Prérequis¶

• Un compte VoidSign (la configuration de la facturation n'est requise qu'après avoir dépassé les 3 demandes de signature gratuites)
• Un endpoint HTTPS accessible publiquement pour recevoir les livraisons de webhooks

Configurer un webhook¶

Les webhooks sont créés et gérés via l'interface web VoidSign à l'adresse https://app.voidsign.com/pro/api/webhooks.

Lors de la création d'un webhook, vous fournissez :

• Un nom pour le webhook
• Une URL d'endpoint HTTPS où les événements seront livrés
• Les événements auxquels s'abonner (ou * pour tous les événements)

Après la création, un secret de signature (commençant par whsec_) est généré et affiché une seule fois.

Vous pouvez envoyer un événement de test hello depuis l'interface web à tout moment pour vérifier que votre endpoint est accessible et fonctionne correctement.

Pour la liste complète des types d'événements, des schémas de payload et des en-têtes HTTP, consultez la référence Événements webhook.

Exigences de réponse¶

Votre endpoint doit retourner un code de statut HTTP 2xx pour accuser réception. Toute réponse non-2xx est considérée comme un échec et déclenche des réessais.

Votre endpoint doit répondre dans un délai de 15 secondes. Les requêtes qui expirent sont traitées comme des échecs.

Pour les détails sur le comportement de réessai, consultez Événements webhook : Comportement de réessai.

Vérifier les signatures¶

Chaque livraison de webhook est signée avec HMAC-SHA256 afin que vous puissiez vérifier qu'elle provient de VoidSign et n'a pas été altérée. La signature suit la spécification Standard Webhooks v1.

Pour vérifier une signature :

1. Extrayez les en-têtes webhook-id, webhook-timestamp et webhook-signature de la requête.
2. Prenez votre secret de signature (par exemple whsec_dGhpcyBpcyBub3QgYSByZWFsIHNlY3JldA==), supprimez le préfixe whsec_ et décodez le reste en base64 pour obtenir les octets du secret.
3. Concaténez le contenu à signer : {webhook-id}.{webhook-timestamp}.{raw_request_body} (les champs sont séparés par des points).
4. Calculez le HMAC-SHA256 du contenu à signer en utilisant les octets du secret comme clé.
5. Encodez le condensé résultant en base64.
6. Préfixez avec v1, pour former la signature attendue : v1,{base64_digest}.
7. Comparez la signature attendue avec la valeur de l'en-tête webhook-signature.

Pseudocode :

secret_bytes  = base64_decode(remove_prefix(signing_secret, "whsec_"))
sign_content  = "{webhook-id}.{webhook-timestamp}.{body}"
digest        = hmac_sha256(key=secret_bytes, message=sign_content)
expected      = "v1," + base64_encode(digest)
valid         = constant_time_equal(expected, webhook-signature)

Désactiver un webhook¶

Un webhook se désactive depuis l'interface web (https://app.voidsign.com/pro/api/webhooks).

Récupérer après une fuite de secret¶

Le secret de signature (whsec_) ne peut pas être tourné sur un webhook existant : il n'existe pas d'endpoint de rotation de secret. Si votre secret est compromis, procédez ainsi pour éviter toute interruption :

1. Créez un nouveau webhook pointant vers la même URL d'endpoint. Un nouveau secret whsec_ est généré ; copiez-le immédiatement.
2. Acceptez les deux secrets côté serveur pendant une courte fenêtre de transition : validez chaque livraison en essayant successivement l'ancien puis le nouveau secret.
3. Désactivez l'ancien webhook une fois que vous ne recevez plus que des livraisons signées avec le nouveau secret.