Vous pourriez avoir besoin d’être averti chaque fois qu’un événement intéressant se produit dans votre espace de travail. C’est à cela que servent les webhooks.
Configurer un endpoint de webhook
Depuis le menu Développeur de votre espace de travail, vous pouvez configurer l’URL sur laquelle vous souhaitez être notifié, ainsi que les événements auxquels vous souhaitez vous abonner.
Pour créer un endpoint de webhook, suivez ces étapes :
- Accédez à la section Endpoints de webhook.
- Cliquez sur le bouton Créer un endpoint.
Notez que seules les URLs sécurisées sont acceptées.
The webhook endpoint que vous venez de créer s’affiche désormais dans votre tableau de bord des endpoints.
Pour plus d’informations sur les événements webhookable, consultez Événements.
Depuis le tableau de bord des endpoints, vous pouvez consulter des informations sur chaque endpoint (nom, URL, date de création et taux de réussite des webhooks envoyés). Vous pouvez également modifier ou supprimer des endpoints depuis le menu des endpoints. Cliquez sur un endpoint pour en afficher les détails.
Afficher les webhooks
Pour afficher tous les webhooks envoyés aux points de terminaison configurés, accédez à la section Webhooks.
Dans la liste des webhooks, vous pouvez voir, entre autres, leur statut (s’ils ont été envoyés correctement ou non) et reprogrammer manuellement l’envoi des webhooks qui n’ont pas pu être envoyés. Lorsque le système ne parvient pas à envoyer un webhook, il réessaie après :
- 1 minute,
- 5 minutes,
- 30 minutes,
- 2 heures,
- 6 heures,
- 24 heures,
- 48 heures.
Pendant toute la période de réessai, le statut du webhook est « en attente ». Si le webhook n’a pas pu être envoyé correctement après tous les réessais, son statut passe à « échoué ».
Pour affiner votre recherche, vous pouvez filtrer les webhooks :
- par période : sélectionnez le format de recherche pour la période, soit Avant une date spécifique, soit Entre deux dates spécifiques, puis entrez une date et une heure,
- par statut : vous pouvez filtrer sur un ou plusieurs statuts parmi les webhooks réussis, en attente ou échoués,
- par point de terminaison : utilisez cette option pour récupérer les webhooks envoyés à une URL spécifique,
- par type d’événement : utilisez cette option pour récupérer les webhooks envoyés pour un type d’événement spécifique,
- par identifiant d’événement : utilisez cette option pour récupérer le webhook associé à un événement spécifique.
Afficher les informations relatives à un webhook spécifique
Cliquez sur un webhook pour afficher ses informations détaillées.
Chaque webhook comprend :
- des détails sur le webhook lui-même,
- le journal de livraison.
Authentification des webhooks
Lorsque Universign envoie un webhook, le corps de la requête est signé et la signature est ajoutée à l’en-tête de la requête afin que vous puissiez vérifier son authenticité et son intégrité. Le format de signature utilisé par Universign est JWS (JSON Web Signature) avec contenu détaché tel que décrit dans la norme RFC7515.
Structure de la signature
Le JWS est ajouté à l’en-tête de la requête webhook dans le champ d’en-tête x-jws-signature. Le JWS comporte 3 sections :
- L’en-tête,
- Les données,
- La signature elle-même.
Remarque : Comme un JWS avec contenu détaché est utilisé, la section des données n’est pas présente dans le JWS mais correspond au corps de la requête au format JSON.
Dans l’exemple ci-dessous, la signature telle qu’elle s’affiche dans l’en-tête de la requête :
- L’en-tête de signature encodé en base64URL est surligné en vert. Il contient l’algorithme ainsi que l’identifiant de la clé publique qui a été utilisée pour signer.
- Entre les deux points, la section des données est vide et déplacée dans le corps de la requête, comme le montre la capture d’écran ci-dessous.
- La signature elle-même, encodée en base64URL, est surlignée en jaune.
The JSON request body:
{
"object": "event",
"id": "evt_x7yrPr1rXJBn",
"type": "transaction.lifecycle.created",
"payload": {
"object": {
"object": "transaction",
"id": "tx_x7yrPr1a566A",
"folder_id": "fol_MJQbbKe5PV7d",
"created_at": "2022-03-15T18:08:16.222Z",
"started_at": null,
"closed_at": null,
"expires_at": null,
"duration": 20160,
"name": "tx_x7yrPr1a566A",
"folder_name": "Mon dossier",
"stalled": false,
"language": "fr",
"sender_name_display": "name_email",
"creator": {
"name": "Jane Doe",
"email": "[email protected]",
"workspace_name": "My workspace",
"api_key_name": null
},
"state": "draft",
"participants": [],
"sealers": [],
"documents": [],
"instructions": {
"sequencing": [],
"signatures": [],
"reviews": []
},
"actions": [],
"metadata": {},
"progress_value": 0,
"ongoing_conversation": false,
"has_unread_message": false,
"origin": "webapp",
"carbon_copy": [],
"watchers": [
"mbr_DDmnn6rrKZa3"
],
"cancel_reason": null,
"cancel_code": null
}
},
"traceId": null,
"createdAt": 1647367696.238
}
L’input de la signature est l’en-tête de signature encodé en base64URL concaténé avec le corps de la requête encodé en base64URL.
Comment vérifier la signature du webhook :
1. Récupérer l’identifiant de la clé utilisé par Universign pour signer le webhook
Pour ce faire, vous devez décoder l’en-tête de signature de base64URL en JSON. Dans l’en-tête décodé ci-dessous, le paramètre alg correspond à l’algorithme utilisé pour signer et le paramètre kid à l’identifiant de la clé publique que vous recherchez.
{"alg":"PS256",
"kid":"scd_78ed7d2bf2a8c4af4a3d3652a89fe8b9f46addb8bc8e7cb69106a6467900f5e6"}
Remarque : PS256 désigne RSASSA-PSS utilisant SHA-256 et MGF1 avec SHA-256, comme décrit dans RFC7518 chapter 3.1.
2. Récupérer la clé publique correspondant à cet ID
Pour ce faire, vous devez accéder à la liste des clés publiques utilisées par Universign, disponible sur https://api.alpha.universign.com/v1/webhooks/jwks.json (Alpha) ou https://api.universign.com/v1/webhooks/jwks.json (Production).
3. Reconstruir les données signées
Concaténez l’en-tête encodé en base64URL avec le corps de la requête encodé en base64URL, comme décrit dans RFC7515. L’en-tête étant déjà encodé en base64URL, vous devez encoder le corps de la requête en base64URL.
Liens utiles
Signature du message ou Traitement MAC
Signature du message ou Validation MAC
4. Vérifier la valeur de signature obtenue à l’aide de la clé publique
À l’aide de l’algorithme récupéré à l’étape 1 et de la clé publique récupérée à l’étape 2, vérifiez que les données obtenues à l’étape 3 correspondent aux données signées dans la signature JWS.
