Configure webhooks

Rechercher

Présentation

Un webhook est un rappel HTTPS défini par l’utilisateur qui est déclenché lorsqu’un événement particulier se produit sur le site source (Adobe Acrobat Sign dans ce cas).

En effet, un webhook n’est rien d’autre qu’un service web qui accepte les requêtes HTTPS POST à partir d’une source. Un webhook est un service REST qui accepte des données ou un flux de données.

Les webhooks sont destinés à la communication interservices dans un modèle de type Push.

Lorsqu’un événement de déclenchement se produit, 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 propres 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 facile 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.
Remarque :

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 déclencher des événements d’accord, de formulaire web ou d’envoi en masse.

La portée du webhook peut inclure l’ensemble du compte ou des groupes individuels via l’interface d’administration. Les portées Utilisateur et Ressource sont également possibles via l’API.

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, Document signé, etc.

Une fois le webhook configuré et enregistré, Acrobat Sign envoie un nouvel objet JSON à l’URL définie chaque fois que l’événement de déclenchement est intercepté. 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 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. 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, qui est 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 vraiment 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

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

// 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 :

  1. Un compte Microsoft doté d’une licence pour créer des applications Azure Functions.
  2. 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. 
  3. 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 :

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. 

Remarque :

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.

Configuration du webhook


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/tous les groupes.
  • Groupe : tous les événements souscrits survenant dans ce groupe déclenchent l’envoi. Les webhooks avec portée de groupe n’existent que dans un seul 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 basés sur les ressources 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 d’entrée de l’URL doit être en écoute sur le port 443.
  • 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.


Événements

Vous trouverez ci-dessous la liste des événements qui peuvent déclencher un envoi vers l’URL du webhook, regroupés par objet.

Chaque événement dispose d’un modèle de la payload JSON qui peut être remise. Cliquez sur le nom de l’événement pour afficher les détails de la payload :

  • Envoyer en masse (anciennement Mega Sign) : les événements d’envoi en masse concernent uniquement la création de l’objet parent Envoyer en masse. Les accords enfants qui en résultent sont suivis en tant qu’événements d’accord.  
    • Envoyer en masse - Tous les événements : tous les événements d’envoi en masse sont inclus. Si d’autres événements sont définis à l’avenir, ils sont automatiquement inclus avec ce paramètre.  La payload JSON est basée sur l’événement individuel déclenché.
    • Envoyer en masse - Créé : lorsqu’un envoi en masse est créé.
    • Envoyer en masse - Partager  : lorsqu’un envoi en masse est partagé.
    • Envoyer en masse - Rappelé : lorsqu’un envoi en masse est rappelé.
  • Formulaire web (anciennement Widgets) : les événements relatifs aux formulaires web concernent uniquement la création du modèle de formulaire web. Les accords enfants qui en résultent sont suivis en tant qu’événements d’accord.
    • Tous les événements de widget : tous les événements de formulaire web sont inclus. Si d’autres événements sont définis à l’avenir, ils sont automatiquement inclus avec ce paramètre.  La payload JSON est basée sur l’événement individuel déclenché.
    • Widget créé : lorsqu’un formulaire web est créé.
    • Widget activé : lorsqu’un formulaire web est activé.
    • Widget désactivé : lorsqu’un formulaire web est désactivé.
    • Widget modifié : lorsqu’un formulaire web est modifié.
    • Widget partagé : lorsqu’un formulaire web est partagé.
    • Échec de la création du widget : lorsqu’un formulaire web est automatiquement annulé en raison d’un problème de conversion.


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, et réduire ainsi le volume total de 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 modèle de formulaire web.
    • Informations sur les participants au widget : informations sur les participants définis dans le modèle de 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 rappels de 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.

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.

Autorité de certification non approuvée

  • 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.

Certificats intermédiaires manquants

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.

  1. 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.

  2. Vérifiez localement le certificat client

    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.  

    Assurez-vous que le fichier .p12 ou .pfx est protégé par une phrase secrète.

  3. 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 :

    1. Générez une clé privée pour le client SSL :

      openssl genrsa -out client.key 2048

    2. Utilisez la clé privée du client pour générer une demande de certificat :

      openssl req -new -key client.key -out client.req

    3. É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

    4. 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

    5. 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

  4. Vérifiez le certificat client par rapport au serveur distant

    • Utilisez Postman pour charger le fichier PFX client dans Paramètres > Certificats.
    • Sélectionnez Ajouter un certificat pour ajouter le certificat client.
    Paramètres Postman

    • Configurez l’en-tête HTTP pour x-adobesign-clientid :
    Configuration de l’en-tête

    Une fois la configuration effectuée, envoyez une requête POST à l’URL de rappel de webhook.

    Vous devez recevoir une réponse 200.

  5. 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:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -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

  • 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 dix 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. 

Par exemple, si vous devez traiter, puis stocker des documents signés. Pour vous assurer que vous pouvez toujours répondre dans les dix secondes, vous devez toujours effectuer votre travail sur un thread distinct ou de manière asynchrone en utilisant une file d’attente.

  • 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 : 

1. Quelles données voulez-vous retourner dans la payload ? 

2. Qui accédera à ces informations ? 

3. Quels seront les décisions ou rapports générés ?

  • Recommandations pour la réception de documents signés : 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. 

L’objet « ConditionalParametersTrimmed » est retourné dans la réponse lorsque cela se produit 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.

Logo Adobe

Accéder à votre compte

Liens rapides

Voir toutes vos formules Gérer vos formules

Legal Notices    |    Online Privacy Policy