Passer au contenu principal
Firma envoie des événements webhook pour notifier votre application des changements du cycle de vie de signature, des finalisations de documents et des activités de l’espace de travail. Les webhooks permettent des intégrations en temps réel sans polling.

Cas d’usage courants

  • Envoyer des notifications internes lorsque des documents sont signés
  • Mettre à jour votre base de données lorsque des demandes de signature sont terminées
  • Déclencher des workflows en aval (facturation, provisionnement, etc.)
  • Suivre les changements de statut des demandes de signature en temps réel

Types d’événements

Firma envoie les types d’événements suivants :

Événements de demande de signature

  • signing_request.created - Nouvelle demande de signature créée
  • signing_request.sent - Demande de signature envoyée aux destinataires
  • signing_request.viewed - Le destinataire a consulté le document
  • signing_request.completed - Tous les destinataires ont terminé de signer
  • signing_request.expired - La demande de signature a expiré
  • signing_request.cancelled - La demande de signature a été annulée
  • signing_request.updated - Métadonnées de la demande de signature mises à jour
  • signing_request.deleted - Demande de signature supprimée (avant l’envoi)
  • signing_request.certificate.generated - Certificat de signature généré
  • signing_request.reminder.sent - Rappel envoyé aux destinataires

Événements de destinataire

  • signing_request.recipient.signed - Le destinataire a terminé la signature
  • signing_request.recipient.declined - Le destinataire a refusé de signer
  • signing_request.recipient.identity_changed - Le destinataire a changé son identité (nom, société, etc.) pendant la signature
  • signing_request.recipient.email_bounced - Un e-mail envoyé au destinataire a généré un rebond

Événements de modèle

  • template.updated - Modèle modifié
  • template.used - Modèle utilisé pour créer une demande de signature

Événements de cachet d’organisation

  • organization_seal.created - Nouveau cachet créé
  • organization_seal.updated - Image du cachet remplacée (nouvelle version), cachet renommé ou statut par défaut modifié
  • organization_seal.deleted - Cachet révoqué
  • organization_seal.erased - Lignage de cachet révoqué définitivement effacé

Événements de cachet dans les demandes de signature

  • signing_request.seal.applied - Cachet appliqué à un document
  • signing_request.seal.paused - Participant de cachet mis en pause (cachet révoqué avec arrêt des applications en cours, ou incohérence d’intégrité)
  • signing_request.seal.swapped - Participant de cachet en pause échangé contre un autre cachet

Événements d’espace de travail

  • workspace.created - Nouvel espace de travail créé
  • workspace.updated - Espace de travail modifié

Événements de domaine

  • domain.verified - Domaine vérifié avec succès
  • domain.verification.failed - Échec de la vérification du domaine

Deux niveaux d’activation

La livraison des webhooks nécessite que les deux interrupteurs soient activés : un interrupteur par webhook et un interrupteur maître au niveau du compte. Les deux sont indépendants, si bien qu’un webhook peut être créé et activé correctement sans jamais déclencher le moindre événement. Au moins une portée (entreprise ou espace de travail) doit avoir son interrupteur maître activé pour que tout webhook de cette portée soit livré. Activer l’interrupteur maître de l’espace de travail génère également un secret de signature pour cet espace de travail s’il n’en existe pas déjà un.
POST /webhooks/{id}/test contourne l’interrupteur maître. Une livraison de test peut réussir même si l’interrupteur maître est désactivé et que les événements réels ne sont pas livrés - un test réussi ne confirme pas que les événements réels se déclencheront.
Lorsque l’interrupteur maître est désactivé, Firma ignore l’événement avant même d’enregistrer une tentative de livraison. consecutive_failures reste à 0 et le webhook n’affiche aucun historique d’échec, alors même que rien n’est livré - il n’y a aucune erreur pour vous alerter.

Autorisations

Activer ou désactiver l’interrupteur maître au niveau de l’entreprise nécessite un accès propriétaire ou administrateur de l’entreprise ; les membres en lecture seule ne peuvent ni l’activer ni le désactiver. Toute tentative de le faire sans autorisations suffisantes renvoie une erreur de permission.

Créer un webhook

Créez des webhooks via l’API ou le tableau de bord :
Votre URL de webhook doit utiliser HTTPS et répondre en moins de 5 secondes. Utilisez POST /webhooks/{id}/test après la création pour vérifier que votre point de terminaison reçoit correctement les événements.

Structure de la charge utile du webhook

L’id d’un destinataire (dans recipient ou recipients) est la clé d’accès à la signature de ce destinataire (/signing/{id}) : traitez-la comme un secret. Tous les événements partagent l’enveloppe id, type, created_at, company_id, workspace_id et data ; cet exemple correspond à un événement signing_request.completed :
Les livraisons de test de POST /webhooks/{id}/test utilisent une structure différente : type (webhook.test), webhook_id, timestamp et data. Elles n’ont pas d’id, ignorez donc votre contrôle d’idempotence pour celles-ci.

Sécurité : vérification de la signature (obligatoire)

Vérifiez toujours les signatures des webhooks pour éviter les attaques par usurpation. Ne traitez pas les webhooks sans vérification de signature.
Firma signe toutes les requêtes webhook avec HMAC SHA-256. Votre point de terminaison de webhook reçoit ces en-têtes :
  • X-Firma-Signature - Signature HMAC utilisant le secret de signature actuel
  • X-Firma-Signature-Old - Signature HMAC utilisant le secret précédent (pendant la période de grâce de rotation de 7 jours)
  • X-Firma-Event - Type d’événement (par ex., signing_request.completed)
  • X-Firma-Delivery - Identifiant de la livraison de cet événement à votre point de terminaison. Il reste identique à chaque nouvelle tentative, automatique ou manuelle. Utilisez l’id de la charge utile pour identifier l’événement.

Format de la signature

Firma utilise un en-tête de signature horodaté :
  • En-tête : X-Firma-Signature: t=1707500000,v1=abc123def456...
  • t = Horodatage Unix (secondes) au moment de la génération de la signature
  • v1 = Empreinte hexadécimale HMAC-SHA256
  • Format de la charge utile signée : {timestamp}.{json_body}
  • La clé HMAC est votre secret de signature exactement tel qu’il est affiché dans le tableau de bord (64 caractères). Ne le décodez pas comme une valeur hexadécimale.
  • X-Firma-Signature et X-Firma-Signature-Old contiennent chacun leur propre t, lisez donc l’horodatage dans l’en-tête que vous vérifiez.
Exemple :

Obtenir votre secret de signature

  1. Accédez à votre tableau de bord Firma
  2. Consultez les détails du webhook pour récupérer le secret de signature
  3. Stockez le secret de manière sécurisée (variable d’environnement ou gestionnaire de secrets)

Exemple de vérification - Node.js (Express)

Exemple de vérification - Python (Flask)

Gestion de la rotation des secrets

Faites la rotation de votre secret de signature de webhook depuis le tableau de bord, ou avec POST /webhooks/rotate-secret pour les webhooks d’entreprise ou POST /workspaces/{id}/webhooks/rotate-secret pour les webhooks d’espace de travail. Via l’API, vous pouvez faire la rotation d’un secret une fois par heure. Les webhooks d’un espace de travail sont signés avec le secret propre à cet espace de travail, et non avec le secret de l’entreprise.
  1. Firma génère un nouveau secret
  2. Pendant 7 jours, Firma envoie les deux signatures :
  • X-Firma-Signature (nouveau secret)
  • X-Firma-Signature-Old (secret précédent)
  1. Après 7 jours, seule X-Firma-Signature est envoyée. GET /webhooks/secret-status ou GET /workspaces/{id}/webhooks/secret-status renvoie grace_period_ends_at.
Firma ne conserve qu’un seul secret précédent. Si vous faites une nouvelle rotation pendant les 7 jours, le secret précédent est remplacé et un point de terminaison qui utilise encore le secret d’avant la première rotation ne peut immédiatement plus vérifier les livraisons. Déployez chaque nouveau secret avant de faire une nouvelle rotation.
Mise en œuvre : Vérifiez X-Firma-Signature avec le secret configuré pour votre point de terminaison. Si cette vérification échoue, vérifiez X-Firma-Signature-Old avec le même secret. Jusqu’au déploiement du nouveau secret, le secret configuré est le précédent, qui est celui avec lequel X-Firma-Signature-Old est signée. Après son déploiement, X-Firma-Signature correspond. Déployez le nouveau secret dans les 7 jours et configurez un seul secret à la fois : un point de terminaison qui accepte les deux secrets continue à faire confiance à l’ancien.

Si un secret risque d’être compromis

  1. Faites immédiatement la rotation du secret.
  2. Déployez sans attendre le nouveau secret sur votre point de terminaison.
À partir de ce moment, une requête signée avec l’ancien secret échoue aux deux vérifications sur votre point de terminaison, même si Firma envoie encore X-Firma-Signature-Old. Le chevauchement de 7 jours ne prolonge donc pas la confiance accordée à l’ancien secret.

Comportement de nouvelle tentative

Firma ne suit pas les redirections HTTP lors de la livraison des webhooks. Enregistrez l’URL exacte servie par votre serveur, y compris son schéma, son nom d’hôte, son chemin et la présence ou l’absence d’une barre oblique finale. Firma réessaie automatiquement les livraisons de webhook échouées :
  • Tentatives : Jusqu’à 3 par événement : immédiatement, puis au moins 5 minutes après le premier échec, puis au moins 1 heure après le deuxième. Les nouvelles tentatives s’exécutent selon un cycle de 5 minutes, prévoyez donc environ 5 à 10 minutes, puis 60 à 65 minutes, ou davantage si de nombreuses nouvelles tentatives sont en file d’attente.
  • Délai d’expiration : Votre point de terminaison doit répondre en moins de 5 secondes
  • Succès : Tout code de statut 2xx indique un succès. Les redirections comptent comme des échecs.
  • Même événement, nouvelle signature : Chaque tentative contient le même X-Firma-Delivery et, pour les événements réels, le même id de charge utile, et est signée à nouveau avec un nouvel horodatage. L’ordre des clés JSON du corps d’une nouvelle tentative peut différer de celui de la première, vérifiez donc toujours le corps brut exactement tel qu’il a été reçu.
  • Désactivation automatique : Lorsque consecutive_failures atteint 50, le webhook est désactivé automatiquement et Firma envoie un e-mail au propriétaire du compte. Réactivez-le avec PUT /webhooks/{id} ("enabled": true) ou dans le tableau de bord.
  • Après la dernière tentative : Un événement qui échoue aux 3 tentatives ne fait pas l’objet d’une nouvelle tentative automatique. Un administrateur peut le relancer depuis le journal des événements du webhook dans le tableau de bord.
  • Sans nouvelle tentative : Les livraisons de test de POST /webhooks/{id}/test sont envoyées une seule fois. Une livraison vers une URL qui échoue au contrôle d’adresse effectué par Firma au moment de la livraison (par exemple, une URL qui se résout en une adresse privée ou de bouclage) échoue sans nouvelle tentative.
Bonne pratique : Répondez immédiatement avec 200, puis traitez les événements de manière asynchrone (file d’attente, tâche en arrière-plan, etc.) pour éviter les délais d’expiration.

Limites de livraison

Les webhooks sont des notifications, pas un journal complet des événements :
  • Les événements ne sont pas livrés dans un ordre garanti et un événement relancé peut arriver après un événement ultérieur. Utilisez le champ created_at de la charge utile comme indication et récupérez l’état actuel depuis l’API.
  • Les événements générés lorsqu’un webhook ou son interrupteur maître est désactivé ne sont pas stockés et ne sont pas livrés ultérieurement. La réactivation d’un webhook ne les rejoue pas.
  • Lorsqu’un webhook a déjà 100 événements sur les 60 dernières secondes, les nouveaux événements qui lui sont destinés sont ignorés et ne sont jamais livrés.
  • Il n’existe aucune API permettant de répertorier ou de rejouer les événements. Pour effectuer un rapprochement après une interruption, répertoriez les demandes de signature avec GET /signing-requests (par exemple status=finished&sort_by=finished_on&sort_order=desc), puis récupérez chacune avec GET /signing-requests/{id}.

Idempotence

Gérez toujours les événements dupliqués en utilisant l’id de l’événement :

Surveiller l’état de santé du webhook

Surveillez l’état de santé de votre webhook en consultant les détails du webhook :
La réponse inclut :
  • consecutive_failures - Compteur d’échecs utilisé pour la désactivation automatique. Il revient à 0 après une livraison réussie.
  • enabled - Indique si le webhook est actif. Il est désactivé automatiquement lorsque consecutive_failures atteint 50.
  • auto_disabled_at - Moment où le webhook a été désactivé automatiquement, sinon null
Limite de débit : Chaque endpoint de /webhooks autorise 60 requêtes par minute par clé API. POST /webhooks/{id}/test autorise 10 requêtes par minute.

Dépannage

Problèmes courants

Les webhooks sont configurés mais les événements ne se déclenchent pas C’est la cause la plus fréquente des signalements « mon webhook ne fonctionne pas ». La configuration par webhook peut être entièrement correcte alors que l’interrupteur maître au niveau du compte est désactivé, ce qui ignore silencieusement chaque événement.
  • Vérifiez que l’interrupteur maître est activé pour la bonne portée : les webhooks au niveau de l’entreprise nécessitent que l’interrupteur de l’entreprise soit activé, les webhooks au niveau de l’espace de travail nécessitent que l’interrupteur de cet espace de travail soit activé.
  • Ne considérez pas un test réussi comme une preuve - POST /webhooks/{id}/test contourne l’interrupteur maître, il peut donc réussir alors que les événements réels ne se déclenchent pas.
  • Vérifiez consecutive_failures sur le webhook - s’il affiche 0 et qu’aucun événement n’apparaît, cela pointe également vers l’interrupteur maître, puisque les événements ignorés ne sont jamais enregistrés comme des tentatives de livraison échouées.
  • Si vous ne trouvez pas ou ne pouvez pas basculer l’interrupteur maître, il se peut que vous n’ayez pas les autorisations de propriétaire ou d’administrateur sur l’entreprise ; demandez à un propriétaire ou un administrateur de l’activer depuis Paramètres > Webhooks.
401 Unauthorized / Signature invalide
  • Vérifiez que vous utilisez le bon secret de signature
  • Vérifiez que vous hachez le corps brut de la requête (et non le JSON parsé)
  • Assurez-vous d’utiliser HMAC SHA-256, et non un autre algorithme de hachage
Délais d’expiration / Erreurs 504
  • Répondez immédiatement avec 200, traitez de manière asynchrone
  • Vérifiez que votre point de terminaison répond en moins de 5 secondes
  • Utilisez des tâches/files d’attente en arrière-plan pour le traitement lourd
Événements dupliqués
  • Mettez en œuvre l’idempotence en utilisant l’id de l’événement
  • Stockez les identifiants d’événements traités dans votre base de données
Webhook désactivé automatiquement
  • Vérifiez consecutive_failures et les événements récents dans le journal des événements du webhook du tableau de bord
  • Corrigez les problèmes du point de terminaison, puis réactivez le webhook via l’API ou le tableau de bord

Tester les webhooks localement

Utilisez un service de tunnel comme ngrok pour le développement local :

Liste de contrôle pour la production

  • Vérifiez les signatures HMAC sur toutes les requêtes de webhook
  • Gérez la rotation des signatures (vérifiez à la fois X-Firma-Signature et X-Firma-Signature-Old)
  • Répondez avec 200 en moins de 5 secondes
  • Traitez les événements de manière asynchrone (files d’attente/tâches en arrière-plan)
  • Mettez en œuvre l’idempotence en utilisant l’id de l’événement
  • Stockez le secret de signature de manière sécurisée (variable d’environnement ou gestionnaire de secrets)
  • Surveillez la métrique consecutive_failures via le point de terminaison GET du webhook
  • Configurez des alertes pour les échecs de webhook
  • Enregistrez tous les événements webhook pour le débogage
  • Testez avec tous les types d’événements souscrits
  • Restez dans les limites de débit (voir le Guide des limites de débit)

Prochaines étapes