Exemple de code JavaScript permettant de récupérer l’ID client, de le valider, puis de le retourner dans l’en-tête de réponse
- Intégrations d’Adobe Acrobat Sign
- Nouveautés
- Versions de produit et cycle de vie
- Acrobat Sign pour Saleforce
- Installation du package
- Configuration du package
- Guide de l’utilisateur
- Guide du développeur
- Guide de personnalisation avancée
- Guide de mappage de champs et modèles
- Guide d’utilisation de l’application mobile
- Guide d’automatisation des flux
- Guide de Document Builder
- Configuration de documents volumineux
- Guide de mise à niveau
- Notes de mise à jour
- Forum aux questions
- Guide de dépannage
- Articles supplémentaires
- Acrobat Sign pour Microsoft
- Acrobat Sign pour Microsoft 365
- Acrobat Sign pour Outlook
- Acrobat Sign pour Word/PowerPoint
- Acrobat Sign pour Teams
- Acrobat Sign pour Microsoft PowerApps et Power Automate
- Connecteur Acrobat Sign pour Microsoft Search
- Acrobat Sign pour Microsoft Dynamics
- Acrobat Sign pour Microsoft SharePoint
- Présentation
- SharePoint sur site : guide d’installation
- SharePoint sur site : guide de mappage de modèles
- SharePoint sur site : guide de l’utilisateur
- SharePoint sur site : notes de mise à jour
- SharePoint en ligne : guide d’installation
- SharePoint en ligne : guide de mappage de modèles
- SharePoint en ligne : guide de l’utilisateur
- SharePoint en ligne : guide de mappage de formulaires web
- SharePoint en ligne : notes de mise à jour
- Acrobat Sign pour Microsoft 365
- Acrobat Sign pour ServiceNow
- Acrobat Sign pour les RH ServiceNow
- Acrobat Sign pour SAP SuccessFactors
- Acrobat Sign pour Workday
- Acrobat Sign pour NetSuite
- Acrobat Sign pour SugarCRM
- Acrobat Sign pour VeevaVault
- Acrobat Sign pour Coupa BSM Suite
- Documentation du développeur Acrobat Sign
Présentation
Un webhook est une requête HTTPS définie par l’utilisateur qui est déclenchée lorsqu’un événement souscrit se produit sur le site source (Adobe Acrobat Sign dans ce cas).
Un webhook n’est rien d’autre qu’un service REST qui accepte des données ou un flux de données.
Les webhooks sont destinés à la communication entre services dans un Modèle PUSH.
Lorsqu’un événement souscrit se déclenche, Acrobat Sign crée une requête HTTPS POST avec un corps JSON et la transmet à l’URL spécifiée.
Les webhooks offrent plusieurs avantages par rapport à la méthode de rappel précédente :
- Les administrateurs peuvent activer leurs webhooks sans avoir à impliquer l’assistance Acrobat Sign pour répertorier l’URL de rappel.
- Les webhooks sont meilleurs en matière d’actualisation des données, d’efficacité de la communication et de sécurité. Aucune interrogation n’est requise.
- Les webhooks permettent de définir facilement différents niveaux de portée (compte/groupe/utilisateur/ressource).
- Les webhooks constituent une solution d’API plus moderne, permettant une configuration plus directe des applications modernes.
- Plusieurs webhooks peuvent être configurés par portée (compte/groupe/utilisateur/ressource) alors que les rappels doivent impérativement être uniques.
- Les webhooks permettent de sélectionner les données à retourner, là où les rappels sont une solution de type « tout ou rien ».
- Les métadonnées transférées avec un webhook peuvent être configurées (de base ou détaillées).
- Les webhooks sont beaucoup plus faciles à créer, modifier ou désactiver selon les besoins, car leur interface utilisateur est entièrement sous le contrôle de l’administrateur.
ce document porte principalement sur l’interface utilisateur Webhooks dans l’application web Acrobat Sign (auparavant Adobe Sign).
Les développeurs qui recherchent des détails sur l’API trouveront des informations supplémentaires ici :
Utilisation
Les administrateurs doivent d’abord disposer d’un service webhook prêt à accepter le transfert entrant depuis Acrobat Sign. Il existe de nombreuses options à cet égard, et tant que le service peut accepter les requêtes POST et GET, le webhook est efficace.
Une fois le service en place, un administrateur Acrobat Sign peut créer un webhook à partir de l’interface Webhook dans le menu Compte du site Acrobat Sign.
Les administrateurs peuvent configurer le webhook pour qu’il se déclenche pour des événements d’accord, de formulaire web (widget) ou d’envoi en masse (Mega Sign). La ressource Modèle de bibliothèque (Document de bibliothèque) peut également être configurée via l’API.
La portée du webhook peut inclure l’ensemble du compte ou des groupes individuels via l’interface d’administration. L’API permet une plus grande granularité grâce à la sélection des portées UTILISATEUR ou RESSOURCE.
Le type de données envoyé vers l’URL est configurable et peut inclure les éléments suivants : Informations sur l’accord, Informations sur les participants, Informations sur les documents, etc.
Une fois le webhook configuré et enregistré, Acrobat Sign envoie un nouvel objet JSON à l’URL définie à chaque déclenchement de l’événement souscrit. Aucune manipulation en cours du webhook n’est requise, sauf si vous souhaitez modifier les critères de déclenchement d’événement ou la payload JSON.
Vérification de l’intention de l’URL du webhook
Avant d’enregistrer un webhook, Acrobat Sign vérifie si son URL indiquée dans la demande d’enregistrement est destinée à recevoir des notifications ou non. À cette fin, lorsqu’Acrobat Sign reçoit une nouvelle demande d’enregistrement de webhook, il envoie d’abord une demande de vérification à l’URL du webhook. Cette demande de vérification est une requête HTTPS GET envoyée à l’URL du webhook. Elle comporte un en-tête HTTP personnalisé : X-AdobeSign-ClientId. La valeur de cet en-tête est définie sur l’ID client (ID de l’application) de l’application API qui demande la création/l’enregistrement du webhook. Pour enregistrer un webhook, l’URL de celui-ci doit répondre à cette demande de vérification avec un code de réponse 2XX. De plus, elle DOIT renvoyer la même valeur d’ID client de l’une des deux façons suivantes :
- Soit dans un en-tête de réponse X-AdobeSign-ClientId. Il s’agit du même en-tête transmis dans la demande et repris dans la réponse.
- Soit dans le corps de la réponse JSON avec la clé X-AdobeSign-ClientId. Sa valeur correspond à l’ID client envoyé dans la demande.
Le webhook est enregistré uniquement si la réponse est positive (code de réponse 2XX) et si la validation de l’ID client figure dans l’en-tête ou le corps de la réponse. L’objectif de cette demande de vérification est de démontrer que vous souhaitez recevoir des notifications à cette URL de webhook. Si vous avez saisi une URL incorrecte par inadvertance, celle-ci ne peut pas répondre correctement à la demande de vérification de l’intention, et Acrobat Sign n’envoie aucune notification à cette URL. En outre, l’URL du webhook peut également confirmer la réception des notifications uniquement via les webhooks enregistrés par une application spécifique. Pour ce faire, validez l’ID client de l’application transmis dans l’en-tête X-AdobeSign-ClientId. Si l’URL du webhook ne reconnaît pas cet ID client, elle NE DOIT PAS répondre avec le code de réponse positive, et Acrobat Sign doit s’assurer que l’URL n’est pas enregistrée en tant que webhook.
La vérification de l’appel de l’URL du webhook est effectuée dans les scénarios suivants :
- Enregistrement du webhook : si la vérification de l’appel de l’URL du webhook échoue, le webhook n’est pas créé.
- Mise à jour du webhook : INACTIF vers ACTIF : si la vérification de l’appel de l’URL du webhook échoue, l’état du webhook ne devient pas ACTIF.
Réponse à une notification du webhook
Acrobat Sign effectue une vérification implicite de l’intention dans chaque demande de notification de webhook envoyée à l’URL du webhook. Ainsi, chaque requête HTTPS de notification de webhook contient également l’en-tête HTTP personnalisé appelé X-AdobeSign-ClientId. La valeur de cet en-tête est l’ID client (ID de l’application) de l’application qui a créé le webhook. Nous considérons que la notification du webhook a été correctement distribuée si, et uniquement si, une réponse positive (code de réponse 2XX) est retournée et si l’ID client est envoyé dans l’en-tête HTTP (X-AdobeSign-ClientId) ou dans un corps de réponse JSON avec la clé xAdobeSignClientId et une valeur identique à l’ID client. Dans un cas contraire, nous réessayons de distribuer la notification à l’URL du webhook jusqu’à épuisement des tentatives.
Comme mentionné ci-dessus, la valeur de l’en-tête (ID client) X-AdobeSign-ClientId qui est inclus dans chaque demande de notification de Sign doit être reprise dans la réponse de deux manières :
1. En-tête HTTP X-AdobeSign-ClientId et valeur identique à l’ID client
|
---|
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // default value } |
Exemple de code PHP permettant de récupérer l’ID client, de le valider, puis de le retourner dans l’en-tête de réponse |
---|
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // default value } ?> |
2. Corps de la réponse JSON avec la clé xAdobeSignClientId et la valeur identique à l’ID client
Exemple de code JavaScript permettant de récupérer l’ID client, de le valider, puis de le retourner dans le corps de la réponse |
---|
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { "xAdobeSignClientId" : clientid // Return Client Id in the body }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; } |
Exemple de code PHP permettant de récupérer l’ID client, de le valider, puis de le retourner dans le corps de la réponse |
---|
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response body header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // default value } ?> |
Exemple de corps de la réponse JSON |
---|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
Conditions préalables
Vous avez besoin des éléments suivants :
- Un compte Microsoft doté d’une licence pour créer des applications Azure Functions.
- Une application Azure Function existante. Vous pouvez en créer une en consultant l’article https://docs.microsoft.com/fr-fr/azure/azure-functions/functions-create-first-azure-function.
- Connaissances de base de JavaScript, afin que vous puissiez comprendre et écrire le code dans le langage de votre choix.
Procédure de création d’un déclencheur Azure Functions faisant office de webhook Acrobat Sign
Pour créer une fonction Déclencheur HTTP JavaScript :
1. Connectez-vous via votre compte Microsoft https://portal.azure.com/.
2. Ouvrez l’application Azure Function affichée dans l’onglet Applications de fonctions.
La liste d’applications Azure Functions s’ouvre :
3. Sélectionnez l’application dans laquelle vous souhaitez créer cette fonction.
4. Cliquez sur le bouton Créer (+) pour créer une fonction Azure.
5. Sélectionnez le scénario Webhook + API et le langage JavaScript.
6. Cliquez sur Créer cette fonction.
Une nouvelle fonction capable de gérer une demande d’API entrante est créée.
Ajout d’une logique pour enregistrer un webhook Acrobat Sign.
Avant d’enregistrer un webhook, Acrobat Sign vérifie que l’URL du webhook indiquée dans la demande d’enregistrement est réellement destinée à recevoir des notifications ou non. À cette fin, lorsqu’une nouvelle demande d’enregistrement de webhook est reçue par Acrobat Sign, l’application envoie d’abord une demande de vérification à l’URL du webhook. Cette demande de vérification est une requête HTTPS GET envoyée à l’URL du webhook avec un en-tête HTTP personnalisé X-AdobeSign-ClientId. La valeur de cet en-tête est définie sur l’ID client de l’application qui demande la création/l’enregistrement du webhook. Pour enregistrer un webhook, l’URL de celui-ci doit répondre à cette demande de vérification avec un code de réponse 2XX. De plus, elle doit renvoyer la même valeur d’ID client de l’une des deux façons suivantes.
Vous pouvez suivre deux options :
Option 1 : transmission de l’ID client dans X-AdobeSign-ClientId en tant qu’en-tête de réponse
Transmettez X-AdobeSign-ClientId dans l’en-tête de réponse. Il s’agit du même en-tête, qui est transmis dans la demande et repris dans la réponse.
Remplacez le fichier Index.js par l’extrait de code suivant :
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Validate that the incoming ClientID is genuine
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable
body: "Notification Accepted",
headers : {
'x-adobesign-clientid' : req.headers['x-adobesign-clientid']
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
Testez le comportement en simulant la demande :
1. Cliquez sur le bouton Tester situé dans l’angle supérieur droit.
2. Effectuez la demande factice.
Même si les en-têtes de réponse ne sont pas affichés ci-dessus, vous pouvez les observer par simulation via Postman/DHC ou un autre service.
Option 2 : transmission de l’ID client dans le corps de la réponse avec la clé xAdobeSignClientId
Dans le corps de la réponse JSON avec la clé xAdobeSignClientId, sa valeur correspondant à l’ID client envoyé dans l’en-tête de la demande.
Remplacez le fichier Index.js par l’extrait de code suivant :
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Validate that the incoming ClientID is genuine
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable
corps: {
'xAdobeSignClientId' : clientId
},
headers : {
'Content-Type' : 'application/json'
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
Testez le comportement en simulant la demande :
1. Cliquez sur le bouton Tester situé dans le coin supérieur droit.
2. Effectuez la demande factice.
Notez également qu’un même comportement pour l’ID client est attendu lorsque l’URL du webhook reçoit des notifications POST.
Prêt à l’emploi
Une fois que vous avez vérifié le comportement, l’URL du webhook fonctionne conformément aux standards Acrobat Sign. Vous pouvez ensuite mettre à jour la logique personnalisée selon vos besoins.
Obtention de l’URL de la fonction
- Cliquez sur Obtenir l’URL de la fonction.
Copiez l’URL et utilisez-la pour créer des webhooks dans Acrobat Sign.
Création de la fonction AWS Lambda
Pour créer une fonction AWS Lambda, connectez-vous à AWS Management Console, puis sélectionnez le service AWS Lambda dans la liste des services.
- Cliquez sur l’option Créer une fonction Lambda à l’aide de Créer de A à Z.
- Dans la page Configurer la fonction, saisissez le nom de la fonction « lambdaWebhooks » et sélectionnez Node.js 4.3 comme runtime.
- Pour Rôle, choisissez un rôle existant ou créez-en un à partir d’un ou de plusieurs modèles.
- Si vous avez choisi Créer un rôle à partir d’un ou de plusieurs modèles, saisissez un nom de rôle (par exemple role-lamda) et sélectionnez Autorisations Microservices simples dans la liste Modèles de stratégies.
- Cliquez sur le bouton Créer une fonction.
- Sur la page de la nouvelle fonction AWS Lambda, sélectionnez Modifier le code en ligne comme Type d’entrée de code et gardez le gestionnaire index.handler.
- Ajout d’une logique pour enregistrer un webhook Acrobat Sign
Avant d’enregistrer un webhook, Acrobat Sign vérifie que l’URL du webhook indiquée dans la demande d’enregistrement est réellement destinée à recevoir des notifications ou non. À cette fin, lorsqu’une nouvelle demande d’enregistrement de webhook est reçue par Acrobat Sign, l’application envoie d’abord une demande de vérification à l’URL du webhook. Cette demande de vérification est une requête HTTPS GET envoyée à l’URL du webhook avec un en-tête HTTP personnalisé X-AdobeSign-ClientId. La valeur de cet en-tête est définie sur l’ID client de l’application qui demande la création/l’enregistrement du webhook. Pour enregistrer un webhook, l’URL de celui-ci doit répondre à cette demande de vérification avec un code de réponse 2XX. De plus, elle doit renvoyer la même valeur d’ID client de l’une des deux façons suivantes. Notez également qu’un même comportement pour l’ID client est attendu lorsque l’URL du webhook reçoit des notifications POST.
Suivez l’un des deux cas :
Cas 1 : transmission de l’ID client dans X-AdobeSign-ClientId en tant qu’en-tête de réponse
- Transmettez X-AdobeSign-ClientId dans l’en-tête de réponse. Il s’agit du même en-tête, qui est transmis dans la demande et repris dans la réponse.
Extrait de code
Dans le fichier index.js, remplacez l’extrait de code généré automatiquement par le code suivant :
- Transmettez X-AdobeSign-ClientId dans l’en-tête de réponse. Il s’agit du même en-tête, qui est transmis dans la demande et repris dans la réponse.
Exemple de code Node.JS permettant de récupérer l’ID client, de le valider, puis de le retourner dans l’en-tête de réponse |
---|
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId'];
//Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } } |
Cas 2 : transmission de l’ID client dans le corps de la réponse avec la clé xAdobeSignClientId
Dans le corps de la réponse JSON avec la clé xAdobeSignClientId, sa valeur correspondant à l’ID client envoyé dans l’en-tête de la demande.
Extrait de code
Remplacez le fichier Index.js par l’extrait de code suivant :
Exemple de code Node.JS permettant de récupérer l’ID client, de le valider, puis de le retourner dans l’en-tête de réponse |
---|
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId'];
//Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { xAdobeSignClientId : clientid };
var response = { statusCode: 200, body: JSON.stringify(responseBody) };
callback(null,response); } else { callback("Opps!! illegitimate call"); } } |
- Enregistrez la fonction. La fonction Lambda est créée et prête à l’emploi dans un webhook en temps réel.
Configuration d’Amazon API Gateway
Pour rendre cette fonction Lambda accessible au public via une méthode HTTP, nous devons configurer AWS API Gateway à l’aide de notre fonction (créée ci-dessus) en tant que système principal de l’API.
Dans AWS Management Console, sélectionnez API Gateway dans les services AWS et cliquez sur le bouton Créer une API.
- Dans la page Créer une nouvelle API, sélectionnez Nouvelle API, puis saisissez webhooks comme nom de l’API.
- Cliquez sur le bouton Créer une API.
- Sélectionnez la liste déroulante Actions, puis l’option Créer une ressource.
- Cochez l’option Configurer en tant que ressource de proxy et saisissez validation comme Nom de la ressource et {proxy+} dans le Chemin d’accès de la ressource.
- Laissez l’option Activer CORS pour API Gateway décochée, puis cliquez sur le bouton Créer une ressource.
- Laissez le paramètre Proxy de fonction Lambda sélectionné comme Type d’intégration et sélectionnez la zone géographique dans laquelle vous avez créé la fonction Lambda dans la liste déroulante Zone géographique Lambda (il s’agit probablement de la zone géographique dans laquelle vous créez API Gateway).
- Saisissez validation comme Fonction Lambda, puis cliquez sur le bouton Enregistrer.
- Dans la fenêtre contextuelle Ajouter une autorisation à la fonction Lambda, sélectionnez OK.
Si toutes les étapes ci-dessus sont exécutées correctement, un affichage semblable à ce qui suit apparaît :
Déploiement de l’API
L’étape suivante consiste à déployer cette API afin qu’elle soit prête à être utilisée.
- Dans la liste déroulante Actions, sélectionnez Déployer l’API.
- Sélectionnez [Nouvelle étape] dans Étape de déploiement et saisissez prod (ou le nom de votre choix pour identifier cette étape) dans Nom de l’étape.
- Cliquez sur le bouton Déployer.
L’API est maintenant prête à être utilisée. Vous pouvez trouver l’URL d’appel dans la zone bleue comme indiqué ci-dessous :
Notez cette URL, car vous devrez la saisir en tant qu’URL de webhook en temps réel.
Prêt à l’emploi
C’est fait. Utilisez l’URL indiquée ci-dessus avec la mention « /{nodeJSfunctionName} » ajoutée en tant qu’URL de webhook dans la requête d’API POST /webhooks. Une fois que vous avez vérifié le comportement, l’URL du webhook fonctionne conformément aux
standards Acrobat Sign. Vous pouvez ensuite mettre à jour/ajouter la logique personnalisée selon vos besoins.
Options de configuration
La configuration du webhook nécessite la définition de cinq éléments :
- Nom : il est conseillé d’utiliser un nom intuitif que les autres administrateurs peuvent facilement comprendre.
- Portée : envergure du webhook. Le compte et le groupe sont disponibles dans l’interface.
- L’API prend en charge les portées Compte, Groupe, Utilisateur et Ressource.
- Une seule portée par webhook peut être définie.
- URL : URL cible à laquelle Acrobat Sign a envoyé la payload JSON.
- Événements : déclencheur qui provoque la création du fichier JSON par Acrobat Sign et son envoi à l’URL.
- Chaque événement génère une payload différente en fonction de l’événement de déclenchement.
- Plusieurs événements peuvent être inclus dans un webhook.
- Paramètres de notification : les Paramètres de notification identifient les sections de la payload JSON Événement, ce qui vous permet de sélectionner uniquement les sections de l’événement qui sont importantes pour ce webhook (et donc de réduire les données inutiles dans votre URL).
Une fois le webhook défini, cliquez sur Enregistrer. Le nouveau webhook commence à réagir pour déclencher immédiatement des événements.
Configurez l’URL du webhook pour répondre aux demandes de vérification et de notification de webhook conformément au protocole de vérification expliqué ci-dessus. ID client (ID d’application) qui est envoyé aux webhooks créés à partir de l’application web Acrobat Sign : UB7E5BXCXY.
Portées
- Compte : tous les événements souscrits survenant dans le compte déclenchent l’envoi.
- Les administrateurs de compte sont autorisés à afficher tous les webhooks définis pour le compte et tous les groupes de ce compte.
- Groupe : tous les événements souscrits survenant dans le groupe déclenchent l’envoi. REMARQUE : les webhooks de portée de groupe existent uniquement pour ce groupe.
- Les administrateurs de groupe voient uniquement les webhooks dédiés à leur groupe. Ils ne peuvent pas voir les webhooks au niveau du compte ni ceux qui sont liés à d’autres groupes.
- Les comptes pour lesquels la fonctionnalité Utilisateurs dans plusieurs groupes est activée voient l’option permettant de définir le groupe auquel la portée doit être appliquée.
- Compte utilisateur : tous les événements souscrits pour un compte utilisateur déclenchent l’envoi. Les webhooks au niveau de l’utilisateur peuvent uniquement être créés via une API.
- Webhook de niveau ressource : il est créé pour une ressource spécifique. Les événements propres à cette ressource sont envoyés vers l’URL du webhook. Les webhooks de niveau ressource peuvent uniquement être créés via une API.
URL
Une URL de webhook est un serveur qui écoute les messages de notification HTTPS POST entrants qui sont déclenchés lorsque des événements se produisent.
Vous avez besoin de cette URL pour abonner votre webhook aux événements.
- Le client doit inclure une URL HTTPS à laquelle Acrobat Sign peut envoyer une requête POST. Cette URL doit être disponible sur l’Internet public.
- Par exemple, les URI 127.0.0.1 et localhost ne fonctionnent pas.
- Le point de terminaison de l’URL doit être à l’écoute sur le port 443 ou 8443 (décidé par le client lors de la définition de l’URL de rappel).
- Assurez-vous que le webhook prend en charge les requêtes POST pour les notifications d’événements entrants et les requêtes GET pour la demande de vérification.
- L’URL ne doit pas être bloquée par un pare-feu.
Vous trouverez ci-dessous les événements qui peuvent déclencher une transmission de type push vers l’URL du webhook, regroupés par objet et répertoriés dans l’ordre trouvé dans l’interface utilisateur.
La valeur située à gauche correspond à celle qui apparaît dans l’interface utilisateur d’Acrobat Sign. La valeur située à droite correspond au nom du webhook dans l’API.
Pour en savoir plus sur les webhooks et leurs payloads, consultez le Guide pour les développeurs Acrobat Sign.
Accords :
Élément de l’interface utilisateur | Nom du webhook |
Tous les événements liés à l’accord | AGREEMENT_ALL |
Accord créé | AGREEMENT_CREATED |
Accord envoyé | AGREEMENT_ACTION_REQUESTED |
Participant à l’accord terminé | AGREEMENT_ACTION_COMPLETED |
Flux de l’accord terminé | AGREEMENT_WORKFLOW_COMPLETED |
Accord expiré | AGREEMENT_EXPIRED |
Accord supprimé | AGREEMENT_DOCUMENTS_DELETED |
Accord annulé | AGREEMENT_RECALLED |
Accord refusé | AGREEMENT_REJECTED |
Accord partagé | AGREEMENT_SHARED |
Accord délégué | AGREEMENT_ACTION_DELEGATED |
Participant à l’accord modifié | AGREEMENT_ACTION_REPLACED_SIGNER |
Accord modifié | AGREEMENT_MODIFIED |
Modification de l’accord réceptionnée | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
Courrier électronique de l’accord consulté | AGREEMENT_EMAIL_VIEWED |
Courrier électronique de l’accord non remis | AGREEMENT_EMAIL_BOUNCED |
Échec de la création de l’accord | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
Accord synchronisé après l’événement hors ligne | AGREEMENT_OFFLINE_SYNC |
Accord téléchargé par l’expéditeur | AGREEMENT_UPLOADED_BY_SENDER |
Accord sécurisé | AGREEMENT_VAULTED |
Identité sociale du participant à l’accord authentifiée | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
Authentification du participant à l’accord fondée sur les connaissances | AGREEMENT_KBA_AUTHENTICATED |
Rappel d’accord envoyé | AGREEMENT_REMINDER_SENT |
Nom du signataire de l’accord modifié par le signataire | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
Webhooks d’accord uniquement disponibles via l’API | |
s.o. | AGREEMENT_EXPIRATION_UPDATED |
s.o. |
AGREEMENT_READY_TO_NOTARIZE |
s.o. |
AGREEMENT_READY_TO_VAULT |
Envoi en masse :
Élément de l’interface utilisateur | Nom du webhook |
Envoi en masse - Tous les événements | MEGASIGN_ALL |
Envoi en masse - Créé |
MEGASIGN_CREATED |
Envoi en masse - Partagé |
MEGASIGN_SHARED |
Envoi en masse - Rappelé |
MEGASIGN_RECALLED |
Formulaires web :
Élément de l’interface utilisateur | Nom du webhook |
Formulaire web - Tous les événements | WIDGET_ALL |
Formulaire web créé |
WIDGET_CREATED |
Formulaire web activé |
WIDGET_ENABLED |
Formulaire web désactivé |
WIDGET_DISABLED |
Formulaire web modifié |
WIDGET_MODIFIED |
Formulaire web partagé |
WIDGET_SHARED |
Échec de création du formulaire web |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Modèles de bibliothèque (API uniquement) :
Élément de l’interface utilisateur | Nom du webhook |
s.o. | LIBRARY_DOCUMENT_ALL |
s.o. | LIBRARY_DOCUMENT_CREATED |
s.o. | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
s.o. | LIBRARY_DOCUMENT_MODIFIED |
Paramètres de notification
Les paramètres de notification vous permettent de personnaliser la payload JSON en fonction d’éléments spécifiques de l’événement.
Par exemple, dans un événement Participant à l’accord modifié, il se peut que vous ne souhaitiez que les Informations sur l’accord et les Informations sur les participants, sans les Informations sur les documents, afin de réduire la taille totale du fichier JSON envoyé à l’URL du webhook.
- Accord
- Informations sur l’accord : informations détaillées sur l’accord, basées sur l’état de celui-ci au moment du déclenchement de l’événement.
- Infos sur les documents de l’accord : inclut toutes les informations sur les documents générés suite à l’événement.
- Infos sur les participants à l’accord : inclut toutes les informations sur les participants à la suite de l’événement.
- Document signé de l’accord : fournit le PDF signé.
- Applicable à Flux de l’accord terminé et Tous les événements liés à l’accord.
- Envoyer en masse
- Infos Envoyer en masse : informations détaillées sur l’objet Envoyer en masse qui a déclenché l’événement.
- Formulaire web
- Informations sur le widget : informations détaillées sur le formulaire web qui a déclenché l’événement.
- Informations sur les documents du widget : informations sur les documents associées au formulaire web.
- Informations sur les participants au widget : informations sur les participants définis dans le formulaire web.
Authentification SSL bidirectionnelle
Le protocole SSL bidirectionnel, souvent appelé SSL côté client ou TLS mutuel, est un mode de protocole SSL dans lequel le serveur et le client (navigateur web) présentent tous deux des certificats pour s’identifier.
Les administrateurs de compte peuvent configurer un certificat côté client dans la page Paramètres de sécurité.
Acrobat Sign vérifie les certificats SSL lors de la remise des payloads à l’URL du webhook. Les webhooks qui échouent à la vérification des certificats SSL ne remettent pas correctement la payload JSON.
Utilisez le protocole SSL bidirectionnel pour authentifier le client (Acrobat Sign) et le service d’écoute afin de vous assurer que seul Acrobat Sign peut accéder à l’URL du webhook.
Si le webhook a été créé par une application partenaire, il utilise un certificat client (le cas échéant) du compte de l’application partenaire pour s’identifier lors des envois de notifications du webhook.
Vous trouverez ci-dessous les questions les plus courantes concernant le processus de vérification du serveur web et la vérification de la certification du client.
Vérification du serveur web
Lors de l’enregistrement d’un webhook, Acrobat Sign vérifie l’URL du serveur webhook.
Les clients ne peuvent pas enregistrer le webhook si la connexion à l’URL de rappel du webhook ne peut pas être établie à partir d’Acrobat Sign.
Non.
L’URL de rappel de webhook ne peut être que HTTPS sur le port 443 ou 8443.
Acrobat Sign bloque le trafic HTTPS sortant vers tous les autres ports.
Un bon moyen de vérifier le certificat du serveur consiste à utiliser DigiCert® SSL Installation Diagnostics Tool.
Saisissez uniquement le nom d’hôte (par exemple, www.digicert.com).
Les problèmes courants sont les suivants :
- Problème : utilisation d’un certificat auto-signé ou émis par une autorité de certification non approuvée.
Solution : utilisez un certificat SSL émis par une autorité de certification publique pour le serveur de rappel de webhook.
- Problème : le serveur n’envoie pas le certificat intermédiaire
Solution : installez les certificats intermédiaires sur le serveur de rappel de webhook.
Pour en savoir plus, consultez le site https://www.digicert.com/kb/ssl-certificate-installation.htm.
Vérification du certificat client
Pour configurer un protocole SSL bidirectionnel pour un webhook, nous demandons à l’administrateur de charger un fichier .p12 (ou .pfx) contenant la clé privée. Le fichier est stocké de manière sécurisée dans le compte client, et l’administrateur a la possibilité de le supprimer à tout moment.
Dans une configuration de webhook bidirectionnel, Acrobat Sign est l’appelant/le client et a besoin de la clé privée pour prouver que l’appel est effectué par Acrobat Sign pour le compte du client.
-
Vérifiez que le protocole SSL bidirectionnel est activé
Le protocole SSL bidirectionnel doit être activé sur le serveur de rappel de webhook.
À l’aide d’un navigateur web, connectez-vous à l’URL de rappel de webhook. Vous devez obtenir :
400 Bad Request No required SSL certificate sent
Cela signifie que le serveur attend du client qu’il envoie des certificats clients (c.-à-d. : le protocole SSL bidirectionnel est activé pour le serveur).
Si vous ne voyez pas le message ci-dessus, alors le protocole SSL bidirectionnel n’est pas activé.
Remarque :vous pouvez utiliser Postman et effectuer une requête POST vers l’URL de rappel de webhook. Vous devez obtenir un résultat similaire.
-
Les informations d’identification du client peuvent être un certificat auto-signé ou un certificat émis par une autorité de certification. Toutefois, il doit être conforme au minimum aux extensions X.509 v3 suivantes :
Extension X.509 v3
Valeur
ExtendedKeyUsage
clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
Le certificat client doit être un fichier PKCS12 avec l’extension .p12 ou .pfx. Il doit inclure à la fois le certificat client (afin que le serveur puisse vérifier l’identité du client) et la clé privée du client (afin que le client puisse signer numériquement les messages pour que le serveur les vérifie pendant la négociation SSL).
Utilisez la commande openssl pour vérifier le fichier p12 (pfx) :
openssl pkcs12 -info -in outfile.p12
La phrase secrète de la clé privée doit être demandée. La sortie doit contenir à la fois des certificats et une clé privée chiffrée :
Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 -----BEGIN CERTIFICATE----- MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE ... JAKQLQ== -----END CERTIFICATE----- Bag Attributes: <No Attributes> subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA -----BEGIN CERTIFICATE----- MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3 ... -----END CERTIFICATE----- Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB Key Attributes: <No Attributes> -----BEGIN ENCRYPTED PRIVATE KEY----- MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA ... FHE= -----END ENCRYPTED PRIVATE KEY-----
Les certificats doivent inclure au minimum le certificat d’entité finale et les certificats intermédiaires. Idéalement, il doit inclure également le certificat d’autorité de certification racine.
Alerte :assurez-vous que le fichier .p12 ou .pfx est protégé par une phrase secrète.
-
Créez un certificat client auto-signé (facultatif)
Les certificats clients peuvent être émis par une autorité de certification ou auto-signés, selon vos besoins.
Pour générer un certificat client auto-signé, utilisez la commande openssl suivante :
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Attention :gardez les fichiers obtenus secrets, car il s’agit de vos certificats d’autorité de certification auto-signés.
Ensuite, générez le fichier client .p12 :
- Générez une clé privée pour le client SSL :
openssl genrsa -out client.key 2048
- Utilisez la clé privée du client pour générer une demande de certificat :
openssl req -new -key client.key -out client.req
- Émettez le certificat client à l’aide de la demande de certificat et du certificat/de la clé de l’autorité de certification :
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Convertissez le certificat client et la clé privée au format pkcs#12 pour une utilisation par les navigateurs :
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Supprimez la clé privée du client, le certificat client et les fichiers de demande du client, car le pkcs12 contient tout ce dont vous avez besoin.
rm client.key client.cer client.req
- Générez une clé privée pour le client SSL :
-
- Utilisez Postman pour charger le fichier PFX client dans Paramètres > Certificats.
- Sélectionnez Ajouter un certificat pour ajouter le certificat client.
- Configurez l’en-tête HTTP pour x-adobesign-clientid :
Une fois la configuration effectuée, envoyez une requête POST à l’URL de rappel de webhook.
Vous devez recevoir une réponse 200.
-
Pourquoi l’application Acrobat Sign refuse-t-elle mon fichier PFX même après que je l’ai vérifié avec Postman ?
Si vous avez suivi le processus de vérification de fichier pfx ci-dessus et qu’Acrobat Sign rejette toujours le fichier pfx, il est probable que le fichier ait été généré par un outil Microsoft pouvant produire un fichier PKCS12 non standard.
Dans ce cas, utilisez les commandes openssl ci-dessous pour extraire les certificats et la clé privée du fichier pfx, puis générez un fichier PKCS12 correctement formaté :
// Extract certificates and private key from pfx file openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.crt -nokeys openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.key -nodes -nocerts // Create new PKCS12 file openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Activation et désactivation
L’accès à la fonctionnalité Webhooks est activé par défaut pour les comptes de formule Entreprise.
Les administrateurs de groupe peuvent créer/contrôler les webhooks qui fonctionnent uniquement au sein de leur groupe.
L’accès à la page Webhooks se trouve dans le volet de gauche du menu Administrateur : Compte > Webhooks.
Activation d’un webhook
Lorsqu’un webhook est créé pour la première fois, il est défini sur le statut Actif.
La page Webhooks d’Acrobat Sign affiche les webhooks actifs par défaut.
Pour activer un webhook inactif :
- Cliquez sur l’icône Options (trois lignes horizontales) à droite de la ligne d’en-tête des webhooks et sélectionnez Afficher tous les webhooks.
- Cliquez sur le webhook inactif pour le sélectionner.
- Les options du webhook s’affichent juste au-dessous de la ligne d’en-tête.
- Cliquez sur Activer.
Le webhook actif commence à envoyer des données à l’URL cible dès que l’événement suivant est déclenché.
Désactivation d’un webhook
Pour désactiver un webhook, vous devez effectuer les actions suivantes :
- Accéder à la page Webhooks.
- Cliquer sur le webhook que vous souhaitez désactiver.
- Sélectionner Désactiver dans les éléments de menu sous la ligne d’en-tête.
- Une fois désactivé, le webhook affiche le statut Inactif.
Affichage ou modification d’un webhook
Les webhooks peuvent être modifiés et enregistrés à tout moment. Dès que vous enregistrez une nouvelle configuration, cette modification prend effet immédiatement.
Seuls Événements et Paramètres de notification peuvent être modifiés.
Si les paramètres Nom, Portée ou URL doivent être modifiés, vous devez créer un nouveau webhook.
Pour modifier les paramètres d’un webhook :
- Accédez à la page Webhooks.
- Cliquez sur le webhook que vous souhaitez modifier.
- Cliquez sur l’option Afficher/Modifier sous la ligne d’en-tête.
- Appliquez les modifications nécessaires, puis cliquez sur Enregistrer.
Suppression d’un webhook
Vous pouvez supprimer un webhook à tout moment.
La suppression d’un webhook entraîne sa destruction du système. Il n’est donc pas possible de récupérer un webhook supprimé.
Les webhooks n’ont pas besoin d’être désactivés en premier lieu.
Pour supprimer un webhook :
- Accédez à Webhooks.
- Cliquez sur le webhook que vous souhaitez supprimer.
- Cliquez sur l’option Supprimer sous la ligne d’en-tête.
- Un message s’affiche pour vérifier que vous souhaitez bien supprimer le webhook. Cliquez sur OK.
Bonnes pratiques
- Abonnez-vous à des événements spécifiques nécessaires pour limiter le nombre de requêtes HTTPS envoyées au serveur : plus vous créez des webhooks spécifiques, moins vous devrez passer en revue le volume de données.
- Faites attention aux doublons : si plusieurs applications partagent la même URL de webhook et qu’un même utilisateur est mappé à chaque application, le même événement est envoyé à votre webhook plusieurs fois (une fois par application). Dans certains cas, votre webhook peut recevoir des événements en double. Votre application de webhook doit tolérer les doublons et procéder à une déduplication par ID d’événement.
- Réagissez toujours rapidement aux webhooks : votre application ne dispose que de cinq secondes pour répondre aux demandes de webhook. Pour la demande de vérification, il s’agit rarement d’un problème, car votre application n’a pas besoin d’effectuer un travail réel pour répondre. Toutefois, pour les demandes de notification, votre application effectue généralement une action qui prend du temps en réponse à la demande. Il est recommandé de travailler sur un thread distinct ou de manière asynchrone en utilisant une file d’attente pour vous assurer de pouvoir répondre dans les cinq secondes.
- Gérez la simultanéité : lorsqu’un utilisateur effectue plusieurs modifications successives rapides, votre application est susceptible de recevoir plusieurs notifications pour le même utilisateur à peu près au même moment. Si vous n’êtes pas attentif à la façon dont vous gérez la simultanéité, votre application peut se retrouver à traiter les mêmes modifications pour un même utilisateur plusieurs fois. Pour tirer parti des webhooks Acrobat Sign, il est nécessaire de bien comprendre l’utilisation des informations. Veillez à poser des questions :
- Quelles données voulez-vous retourner dans la payload ?
- Qui accédera à ces informations ?
- Quels seront les décisions ou rapports générés ?
- Recommandations pour la réception d’un document signé : vous devez prendre en compte plusieurs facteurs pour déterminer comment recevoir un PDF signé d’Acrobat Sign dans votre système de gestion des documents.
Bien qu’il soit parfaitement acceptable de sélectionner simplement l’option Document signé de l’accord lors de la création d’un webhook, vous pouvez envisager d’utiliser l’API Acrobat Sign pour récupérer les documents lorsqu’un événement déclencheur (tel que le statut de l’accord Terminé) est reçu.
Points à prendre en compte...
Limitation de taille de payload JSON
La taille de la payload JSON est limitée à 10 Mo.
Si un événement génère une payload plus importante, un webhook est déclenché, mais les attributs de paramètres conditionnels, si la demande en contient, sont supprimés pour réduire la taille de la payload.
Dans ce cas, l’objet « ConditionalParametersTrimmed » est retourné dans la réponse, pour informer le client que les informations conditionalParameters ont été supprimées.
« conditionalParametersTrimmed » est un objet de type tableau contenant les informations sur les touches qui ont été supprimées.
La troncation est effectuée dans l’ordre suivant :
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
Les documents signés sont d’abord tronqués, suivis des informations sur les participants, des informations sur les documents et enfin des informations détaillées.
Cela peut se produire, par exemple, lors d’un événement de fin d’accord, s’il inclut également un document signé (codé en base 64) ou pour un accord comptant plusieurs champs de formulaire.
Notifications du webhook
Les webhooks Acrobat Sign remettent des notifications qui s’appliquent à tous les participants d’un accord si un webhook est configuré pour cet utilisateur, son groupe ou son compte.
Les événements d’accord sont traités de telle sorte que si un webhook est configuré pour le participant applicable de cet événement, une notification est envoyée à l’URL de ce webhook. En d’autres termes, les webhooks sont déclenchés pour les événements dans tous les accords applicables, même ceux en dehors du groupe ou du compte dans lequel le webhook est configuré.
Les notifications sont envoyées uniquement pour les événements auxquels le participant est associé. Par exemple, l’expéditeur d’un accord reçoit presque toutes les notifications, alors que les destinataires n’en reçoivent qu’à partir du début de leur participation à l’accord, et uniquement pour les événements dans lesquels ils sont impliqués.
Les notifications du webhook suivent le modèle d’authentification et de visibilité actuel d’Acrobat Sign. Les utilisateurs n’ont donc accès à l’accord que lorsque leur participation à un accord commence.
L’expéditeur envoie un accord pour signature à trois signataires.
- Un niveau de compte WebhookX est configuré pour le compte Expéditeurs.
- Signataire1 est membre du même compte que l’expéditeur, mais fait partie d’un groupe différent. Un WebhookY est configuré pour ce groupe.
- Signataire2 est membre d’un autre compte, et un niveau de compte WebhookZ est configuré pour le compte Signataire2.
- Signataire3 est membre du même compte qu’un expéditeur.
L’expéditeur envoie un accord : WebhookX se déclenche à la création de l’accord et à l’envoi de l’accord tandis que WebhookY se déclenche à l’envoi de l’accord.
Le Signataire1 signe : WebhookX se déclenche à l’événement « Participant à l’accord terminé » et à l’envoi de l’accord, WebhookY se déclenche à l’événement « Participant à l’accord terminé » et WebhookZ se déclenche à l’envoi de l’accord.
Le Signataire2 signe : WebhookX se déclenche à l’événement « Participant à l’accord terminé » et à l’envoi de l’accord, tandis que WebhookZ envoie une notification pour l’événement « Participant à l’accord terminé ».
Le Signataire3 signe : WebhookX se déclenche aux événements « Participant à l’accord terminé » et « Flux de l’accord terminé », WebhookY se déclenche à l’événement « Flux de l’accord terminé » et WebhookZ se déclenche à l’événement « Flux de l’accord terminé ».
Nouvelle tentative lorsque le service d’écoute ne fonctionne pas
Si l’URL cible du webhook ne fonctionne pas pour une raison quelconque, Acrobat Sign met en file d’attente le fichier JSON et tente à nouveau la transmission par cycles progressifs durant 72 heures.
Les événements non distribués sont conservés dans une file d’attente pour de nouvelles tentatives. Au cours des 72 heures à venir, les notifications sont remises dans l’ordre dans lequel elles se sont produites, autant que faire se peut.
La stratégie visant à retenter la remise des notifications consiste à doubler le temps entre les tentatives, depuis 1 minute jusqu’à 12 heures, soit 15 tentatives en l’espace de 72 heures.
Si le récepteur du webhook ne répond pas dans les 72 heures et qu’aucune notification n’a été remise au cours des sept derniers jours, le webhook est désactivé. Aucune notification n’est envoyée à cette URL tant que le webhook n’est pas réactivé.
Toutes les notifications adressées entre le moment où le webhook est désactivé et celui où il est réactivé sont perdues.
Adobe
Recevez de l’aide plus rapidement et plus facilement
Nouvel utilisateur ?