Webhooks sur Legalesign
Qu'est-ce que les webhooks
Les webhooks sont vos URLs où Legalesign enverra des mises à jour de statut en temps réel. Vous pouvez créer vos propres URLs ou des systèmes d'automatisation (comme MS Power Automate) peuvent les générer pour déclencher un flux de travail.
Par exemple, dans cette démonstration, nous créons une URL avec Microsoft Power Automate. Nous ajoutons cette URL comme webhook dans Legalesign pour quand des documents sont signés. Le flux Power Automate est déclenché lorsqu'un document est signé et sauvegarde automatiquement ces PDFs nouvellement signés sur Sharepoint. En savoir plus sur MS Power Automate.
Note importante - vous devez avoir les permissions Admin de l'équipe pour recevoir les événements de l'équipe envoyés à votre webhook.
Pourquoi vous avez besoin des webhooks
Les webhooks vous permettent de maintenir un système piloté par les événements. Les webhooks vous tiennent informé de tous les événements au sein de vos groupes. Vous pouvez les utiliser pour créer votre propre tableau de bord en direct et/ou les utiliser pour synchroniser avec votre propre base de données.
Comme mentionné ci-dessus, les webhooks générés par des systèmes d'automatisation comme Power Automate vous permettent de déclencher des procédures de stockage, des emails, de la tenue de registres, etc., qui, combinés à l'API, fournissent tout ce dont vous avez besoin pour l'automatisation des processus.
Un abonnement websocket en temps réel est également disponible. Cela peut être mieux adapté lorsque vous souhaitez des mises à jour en direct côté client sans exposer un point de terminaison webhook. Le websocket expose un ensemble plus large d'événements que les webhooks.
Oui, les webhooks peuvent sembler compliqués, mais ils en valent vraiment la peine et sont excellents pour votre intégration. Continuez à lire.
Types de webhook
- Événements en temps réel
- Tous les événements toutes les 6 minutes (héritage)
- Lors d'un [événement] (héritage)
Pour les webhooks hérités voir : webhooks hérités
Les webhooks sont le plus souvent utilisés pour télécharger un PDF signé. Lorsque vous créez le webhook, appliquez le filtre d'événement 'Final PDF created'. Dans votre code, la requête entrante request.body est en JSON, analysez-la et extrayez documentId = ['data']['uuid']. Ensuite, effectuez la requête API pour télécharger le PDF - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Comment ajouter ou supprimer un webhook
Ajouter ou supprimer un webhook via l'application web
Allez sur le tableau de bord API et cliquez sur la section Webhooks. Le formulaire propose des contrôles simples pour ajouter ou supprimer des webhooks. Vous pouvez éventuellement isoler les événements webhook à certaines équipes et/ou événements.

Vos webhooks reçoivent des événements de tous les comptes où vous êtes admin, en développement comme en production. Utilisez le filtre de groupe pour créer différents webhooks pour vos différents groupes.
Ajouter ou supprimer un webhook via l'API REST
Voir la section 'webhook' en bas de la navigation gauche dans la documentation de l'API : Webhooks API REST
Ajouter ou supprimer un webhook via GraphQL
Nouveau ! Dans le Legalesign GraphiQL Explorer, connecté à votre compte Legalesign, vous avez plein de pouvoir CRUD sur les webhooks. Les webhooks peuvent être listés comme un attribut du type User, et il existe des mutations pour createWebhook, updateWebhook et deleteWebhook.
Que contient un webhook ?
La façon la plus rapide d'inspecter vos données est d'ajouter un webhook, d'envoyer/signer/rejeter quelques documents de test dans l'application web, puis de consulter le journal des webhooks dans le Tableau de bord API Legalesign.
Si vous avez besoin d'une URL webhook temporaire pour les tests, essayez ngrok.
Petit guide sur ngrok : une fois que vous avez téléchargé ngrok, lancez-le dans le terminal avec ./ngrok http 80 et il vous donnera une adresse https. Entrez-la comme votre webhook. Maintenant ouvrez http://127.0.0.1:4040. C'est tout, vous commencerez à voir tous les webhooks et leurs données. Commencez à envoyer et signer des documents de test. Note : Ngrok peut retourner une erreur 5XX, donc vous pouvez vous attendre à voir plusieurs tentatives et messages d'erreur car le système considérera le statut 5XX comme une tentative échouée.
Assurez-vous que votre code recevant le webhook renvoie une réponse 2XX de succès. Si vous avez plusieurs exceptions possibles dans votre code, renvoyez différents codes 5XX. Les journaux de webhook dans le tableau de bord API vous indiqueront alors quelle exception a été déclenchée.
Format du webhook en temps réel
Le format des données peut être selon deux schémas, soit un schéma 'document' soit un schéma 'recipient'. Inspectez l'attribut 'object' pour déterminer le schéma en question.
Les deux schémas ont également un attribut 'event'. Vous pouvez filtrer par objet et optionnellement par événement lors de la création du webhook.
Un tableau de tous les objets et événements possibles est ci-dessous. Cette image illustre un objet document (pour un événement 'created'). Les schémas JSON complets sont en annexe à la fin de cet article.

Les requêtes arrivent en POST contenant du JSON. Veuillez noter que le contenu de 'data' peut s'étendre avec plus de champs au fil du temps.
Utilisez les attributs 'tag'. Vous pouvez définir jusqu'à 3 tags lors de la création d'un document. En utilisant les tags, vous n'aurez peut-être pas à sauvegarder les IDs Legalesign. Vous pouvez aussi utiliser un tag pour enregistrer un secret afin de vérifier la requête entrante (merci Themis pour cette suggestion).
Tableau des combinaisons possibles pour 'object' et 'event' :
| objet | événement |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
| recipient | autoReminderEmail |
| recipient | emailNotification |
La plupart des événements ne se produisent qu'une fois. Les exceptions sont visiting, bounced, emailNotification et autoReminderEmail, qui peuvent survenir plusieurs fois.
N'oubliez pas de désactiver la protection CSRF pour la vue qui reçoit ces requêtes POST.
Voici un exemple d'objet 'recipient', avec l'événement 'bounced' :

Notez emailBounce et emailBounceMessage dans 'data'. 'emailBounceMessage' indiquera le type de rebond comme suit :
- Rebond dur : "Message hard bounced"
- Rebond doux : "Email soft bounced (out of office ou un timeout)"
- Retardé : "Message delayed (vérifiez que le domaine mail existe)"
Le schéma peut recevoir de nouveaux attributs ajoutés à tout moment.
Déboguer les webhooks dans le tableau de bord API
Tous les webhooks sont journalisés et vous pouvez examiner leur contenu ainsi que le code de statut http dans votre tableau de bord API. Pour en savoir plus consultez le Tutoriel tableau de bord
Déclencheur manuel de webhook
Déclenchez manuellement un webhook avec le formulaire en bas de la page Webhooks dans votre Portail Développeur.
Assurez-vous d'utiliser un vrai ID de destinataire ou de document, selon l'événement.
Codes de statut
Cliquez sur ces liens pour voir le tableau de référence des statuts des documents et des statuts des destinataires.
Vérifier un webhook
Le webhook signe le paquet de données avec une clé privée. Vous pouvez vérifier la signature avec la clé publique - télécharger la clé publique.
- La signature se trouve dans l'en-tête X-Signed-SHA256.
- Les données signées correspondent à tout le request.body (en tant que chaîne).
La 'signature' est encodée en base64. Voici un exemple de code de vérification en node.js :
const crypto = require('crypto');
const fs = require('fs');
const cert = fs.readFileSync('/location/of/downloadedCert.crt', 'utf8');
const c = new crypto.X509Certificate(cert);
const k = c.publicKey
let verifier = crypto.createVerify('SHA256');
let rawdata = 'sentdata' //JSON stringify data in request.body
let sha256signature = 'xxx' //value of 'X-Signed-Sha256' request header.
verifier.update(rawdata);
return verifier.verify(k, sha256signature, 'base64');
[1]
Optionnellement, une vérification basée sur HMAC est aussi disponible. Pour HMAC, une clé secrète pour vos webhooks vous est partagée. La valeur signée arrivera dans l'en-tête X-HMAC-SHA256.
Il existe de nombreuses ressources en ligne qui démontrent comment vérifier une valeur HMAC. Un exemple de vérification en python serait :
import hmac, hashlib
sentdata = 'sentdata' # JSON stringify data in request.body
hmacvalue = 'xxx' # value of 'X-HMAC-Sha256' in request header.
v = hmac.new('your secret value'.encode(), 'sentdata'.encode(), hashlib.sha256)
isValid = v.hexdigest() == hmacvalue
Ou un exemple de code Salesforce Apex pour vérifier un HMAC est :
String message = 'JSONstring'; //sent in request.body
String privatekey = 'privateKey'; //shared value you have been given
String hmacvalue = 'xxx'; //value of 'X-HMAC-Sha256' in request header.
Boolean verified = Crypto.verifyHMac('HmacSHA256', Blob.valueOf(message), Blob.valueOf(privatekey), EncodingUtil.convertFromHex(hmacvalue));
Plus de webhooks ?
Si vous avez besoin de plus de webhooks pour différents événements, ou plus de données dans ceux-ci, contactez-nous et soumettez votre demande dans la file de développement.
Référence du schéma
Il existe deux schémas possibles, un pour l'objet 'document' et un autre pour l'objet 'recipient'. Les deux schémas ont des clés de premier niveau 'object' et 'event'. Inspectez l'attribut 'object' pour déterminer le schéma concerné. Ou utilisez un filtre webhook pour ne retourner que les objets document ou uniquement les objets recipient.
Veuillez noter que des attributs peuvent être ajoutés aux schémas à tout moment (mais sans jamais en retirer).
1. Schéma JSON pour l'objet 'document'
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "document"
},
"created": {
"type": "integer",
"description": "unix timestamp"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(created|rejected|finalPdfCreated)$"
},
"data": {
"type": "object",
"properties": {
"tag1": {
"type": "string"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer"
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60)$"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string",
"pattern": "^(signer|approver|witness)$"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
}
},
"required": [
"uuid",
"email",
"order",
"status",
"lastname",
"roleText",
"firstname",
"statusText",
"resourceUri",
"rejectReason"
]
}
]
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"statusText": {
"type": "string",
"pattern": "^(available|fields complete|completed|removed|rejected|unknown)$"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"tag2": {
"type": "string"
},
"group": {
"type": "string"
},
"status": {
"type": "integer",
"pattern": "^(10|20|30|40|50)$"
}
},
"required": [
"tag1",
"recipients",
"groupResourceUri",
"statusText",
"name",
"tag",
"resourceUri",
"uuid",
"tag2",
"group",
"status"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}
2. Schéma JSON pour l'objet 'recipient'
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "recipient"
},
"created": {
"type": "integer",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(emailOpened|bounced|visiting|rejected|completed|autoReminderEmail|emailNotification)$"
},
"data": {
"type": "object",
"properties": {
"tag": {
"type": "string"
},
"tag1": {
"type": "string"
},
"tag2": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"group": {
"type": "string",
"format": "uuid"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer",
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60|70)$"
},
"document": {
"type": "string"
},
"documentName": {
"type": "string"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"emailBounce": {
"type": "integer"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"emailBounceMessage": {
"type": "string"
},
"documentResourceUri": {
"type": "string",
"format": "uri-reference"
}
},
"required": [
"tag",
"tag1",
"tag2",
"uuid",
"email",
"group",
"order",
"status",
"document",
"documentName",
"lastname",
"roleText",
"firstname",
"statusText",
"emailBounce",
"resourceUri",
"rejectReason",
"groupResourceUri",
"emailBounceMessage",
"documentResourceUri"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}