Créer/Modifier un Webhook- Administration (eZsign Web)

Un Webhook est un moyen pour votre application d’être informée en temps réel d’un évènement.

Par exemple, si vous envoyez un contrat et souhaitez être informé dès qu’il est signé, vous pourriez automatiser une vérification du statut du document toutes les 5 minutes sur plusieurs jours jusqu’à ce que vous receviez une réponse indiquant que le document a été signé. Cette approche consomme beaucoup de ressources à chaque appel d’API non nécessaire.

Une meilleure approche consisterait à configurer un Webhook pour surveiller un évènement particulier. Dans cet exemple, l’évènement à surveiller est "DocumentCompleted" du module "Ezsign". Ainsi, dès que le document est signé, une demande sera envoyée à VOTRE serveur pour vous informer de l’évènement qui vient de se produire.

Vous pouvez toujours vous référer à la documentation API d’eZmax pour plus de détails: Documentation API eZmax

Créer un Webhook

• À partir du menu Administration >> Sélectionnez Webhooks.

• Cliquez sur le bouton Nouveau Webhook.

Informations

• Inscrivez le Nom du Webhook.

• Inscrivez l’URL du Webhook. L’URL fournie doit utiliser HTTPS pour des raisons de sécurité.

• Vous devez entrer une adresse courriel où les notifications seront envoyées en cas d’erreur dans la case Courriel en cas d’erreur.

Gestion des erreurs:

eZsign tentera de livrer l’évènement à votre serveur instantanément, mais réessaiera plusieurs fois si votre serveur ne répond pas correctement pour une raison quelconque (voir le calendrier ci-dessous). Après l’épuisement de toutes les tentatives, l’évènement sera transféré au courriel. Le corps du courriel contiendra la demande JSON dans le même format que le Webhook. De cette façon, vous pourrez envoyer la demande à votre serveur en utilisant Postman, Curl ou un outil similaire.

Calendrier de réessai de livraison

Voici le calendrier de réessai approximatif. Puisqu’il y a un délai d’attente de 30 secondes à chaque tentative, il pourrait y avoir une surcharge cumulative allant jusqu’à 3 minutes et demie.

Rapport des tentatives échouées

Si vous ne recevez pas l’évènement lors de la première tentative, il y aura des informations de débogage sur chaque tentative précédente dans le corps de l’évènement. Vous pourrez voir l’horodatage de chaque tentative précédente et le code de retour renvoyé par votre serveur ou une indication de délai d’attente si votre serveur n’a pas répondu.

• Lors de la création d’un Webhook pour eZsign, vous devez sélectionner Module du Webhook >> Module eZsign.

• Vous devez sélectionner l’Évènement du module eZsign approprié à ce Webhook à partir de la liste déroulante, afin de recevoir les notifications pertinentes. Par exemple, pour l’évènement Document complété , vous serez notifié chaque fois qu’un document sera complété.

• À partir de la liste déroulante, vous devrez ensuite sélectionner le Type de dossiers avec lequel le Webhook doit être associé.

Note: vous avez l’option de sélectionner Tous les types de dossiers.

• Pour Ignorer la validation SSL , vous devrez basculer cette option (la validation SSL est appliquée par défaut). La validation SSL sur le Webhook permet de garantir que les données transmises entre les serveurs eZsign et vous (ou un point de terminaison) sont sécurisées grâce à l’utilisation du protocole SSL/TLS. Nous ne recommandons pas d’ignorer cette validation et elle ne devrait être ignorée que dans des cas particuliers.

• Pour Signer les requêtes , vous devrez basculer cette option. Signer les requêtes du Webhook permet de s’assurer que les requêtes reçues proviennent bien de l’expéditeur attendu et qu’elles n’ont pas été altérées entre temps.

Options additionnelles

Si votre serveur nécessite une authentification OAuth 2.0, vous devrez activer l’Utilisation d’une authentification externe en basculant l’option.

Une authentification externe devra être préalablement créée pour l’ajouter au Webhook. Pour plus d’informations, référez-vous à l’article Créer/Modifier/Supprimer une Authentification externe - Administration (eZsign Web).

Une fois l’authentification externe créée, vous pourrez la sélectionner dans le menu déroulant.

• Si vous le désirez, vous pourrez ajouter des Entêtes personnalisés en y inscrivant la Nom de l’entête et la Valeur. Les entêtes personnalisés dans le Webhook vous permettront d’ajouter des informations supplémentaires sur celui-ci.

• Lorsque vous avez terminé, cliquez sur Sauvegarder en haut à droite de votre écran.

Envoyer des tests

• Une fois le Webhook créé vous aurez la possibilité d’envoyer des tests en cliquant sur le bouton Envoyer un test. Cette option vous permettra, pendant le développement, de facilement vous envoyer un test sans avoir à reproduire l’évènement que vous désirez tester.

NOTE : Vous aurez aussi accès à l’historique de la dernière journée et de la dernière semaine. À noter qu’il peut y avoir un délai allant jusqu’à 5 minutes avant que le message du Webhook soit affiché dans l’historique.

Modifier un Webhook

• Pour modifier un Webhook existant, sélectionnez-le à partir de la Liste des Webhooks et cliquez sur Modifier le Webhook.

• Effectuez les changements désirés et cliquez sur Sauvegarder pour les enregistrer.

NOTE : Vous ne pourrez pas supprimer un Webhook, vous pourrez toutefois le rendre inactif.