Présentation des webhooks 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.

Avant de configurer les webhooks, assurez-vous que votre réseau accepte les plages d’adresses IP nécessaires à la fonctionnalité.

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.

Conditions préalables

Vous devez autoriser les plages d’adresses IP pour les webhooks via votre sécurité réseau pour que le service fonctionne. 

Le service d’URL de rappel hérité dans REST v5 utilise les mêmes plages d’adresses IP que le service de webhook.

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.

Activation et désactivation

L’accès à la fonctionnalité Webhooks est activé par défaut pour les comptes Grands comptes.

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.

Limitation de taux basée sur la simultanéité

Les événements de création et de notification de webhook (et de rappel) sont limités au nombre de notifications simultanées qui sont activement envoyées au client à partir du système Acrobat Sign. Cette limite s’applique au compte, pour inclure tous les groupes qu’il contient.
Ce type de limitation de taux empêche un compte mal conçu de consommer une quantité disproportionnée de ressources serveur, ce qui aurait un impact négatif sur tous les autres clients de cet environnement de serveur.

Le nombre d’événements simultanés par compte a été calculé pour que les comptes dont les webhooks sont bien configurés reçoivent leurs notifications dans le plus court délai possible et qu’il soit rare que les notifications soient retardées en raison d’un trop grand nombre de demandes. Voici les seuils actuels :

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 envoient des notifications à l’expéditeur de l’accord et à tout webhook configuré dans le groupe à partir duquel l’accord a été envoyé. Les webhooks dont la portée est au niveau du compte reçoivent tous les événements.

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.