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ééesigning_request.sent- Demande de signature envoyée aux destinatairessigning_request.viewed- Le destinataire a consulté le documentsigning_request.completed- Tous les destinataires ont terminé de signersigning_request.expired- La demande de signature a expirésigning_request.cancelled- La demande de signature a été annuléesigning_request.updated- Métadonnées de la demande de signature mises à joursigning_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 signaturesigning_request.recipient.declined- Le destinataire a refusé de signersigning_request.recipient.identity_changed- Le destinataire a changé son identité (nom, société, etc.) pendant la signaturesigning_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 documentsigning_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èsdomain.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.
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)
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 actuelX-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’idde 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 signaturev1= 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-SignatureetX-Firma-Signature-Oldcontiennent chacun leur propret, lisez donc l’horodatage dans l’en-tête que vous vérifiez.
Obtenir votre secret de signature
- Accédez à votre tableau de bord Firma
- Consultez les détails du webhook pour récupérer le secret de signature
- 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 avecPOST /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.
- Firma génère un nouveau secret
- Pendant 7 jours, Firma envoie les deux signatures :
X-Firma-Signature(nouveau secret)X-Firma-Signature-Old(secret précédent)
- Après 7 jours, seule
X-Firma-Signatureest envoyée.GET /webhooks/secret-statusouGET /workspaces/{id}/webhooks/secret-statusrenvoiegrace_period_ends_at.
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
- Faites immédiatement la rotation du secret.
- Déployez sans attendre le nouveau secret sur votre point de terminaison.
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-Deliveryet, pour les événements réels, le mêmeidde 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_failuresatteint 50, le webhook est désactivé automatiquement et Firma envoie un e-mail au propriétaire du compte. Réactivez-le avecPUT /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}/testsont 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.
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_atde 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 exemplestatus=finished&sort_by=finished_on&sort_order=desc), puis récupérez chacune avecGET /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 :consecutive_failures- Compteur d’échecs utilisé pour la désactivation automatique. Il revient à0après une livraison réussie.enabled- Indique si le webhook est actif. Il est désactivé automatiquement lorsqueconsecutive_failuresatteint 50.auto_disabled_at- Moment où le webhook a été désactivé automatiquement, sinonnull
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}/testcontourne l’interrupteur maître, il peut donc réussir alors que les événements réels ne se déclenchent pas. - Vérifiez
consecutive_failuressur le webhook - s’il affiche0et 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.
- 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
- 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
- Mettez en œuvre l’idempotence en utilisant l’
idde l’événement - Stockez les identifiants d’événements traités dans votre base de données
- Vérifiez
consecutive_failureset 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-SignatureetX-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’
idde 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_failuresvia 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
- Créer un webhook via l’API
- Tester votre webhook avant la mise en production
- Mettre à jour les paramètres du webhook selon les besoins