Utilisation de webhooks

L'exemple ci-dessous illustre l'utilisation de webhooks pour mettre à jour l'état du signataire d'un document dans un cas de figure où plusieurs signatures sont nécessaires. Cette configuration met à jour l'état du signataire d'un document en temps réel (« État du signataire » est le libellé d'une colonne dans un champ de table).

Dans cet exemple précis, vous devez configurer un fournisseur de signature électronique et un workflow Envoyer pour signature en plus du webhook.

Vous trouverez des descriptions détaillées des paramètres de webhook à la page suivante :

Webhooks

Configuration de la signature d'un webhook

Dans Therefore™ Solution Designer, accédez au nœud Intégrations, cliquez avec le bouton droit de la souris sur le nœud Webhooks et sélectionnez « Nouveau webhook ».

Étant donné que seuls les webhooks signés peuvent mettre à jour des informations, vous devez configurer la signature sous « Signature HMAC ». Référez-vous à la documentation du fournisseur tiers pour obtenir la clé secrète partagée et l'en-tête de signature, que vous devrez entrer dans les champs correspondants. À moins qu'ils ne soient nécessaires pour renforcer la sécurité, vous pouvez laisser vides les champs « En-tête d'horodatage » et « Liste verte d'adresses IP ».

Copiez le contenu du champ « Point de terminaison » à l'aide du bouton « Copier dans le Presse-papiers » adjacent et partagez-le avec le fournisseur tiers lors de la configuration du webhook de son côté.

Configuration d'une action de webhook

Selon ce qui doit se produire lorsque des informations sont reçues via le webhook, ajoutez ensuite une action. Dans ce cas de figure, l'état du signataire doit passer d'En attente à Signé. L'action sélectionnée correspond donc à « Mettre à jour données d'index ».

Selon ce qui doit se produire lorsque des informations sont reçues via le webhook, vous devez configurer les onglets appropriés.

Onglet Filtre

Pour terminer cette étape, vous devez consulter la documentation du fournisseur tiers pour déterminer le nom de l'événement dans les données utiles et les valeurs prises en charge. Pour la plupart des fournisseurs, il est possible de configurer le webhook de sorte à n'envoyer des informations que si des événements spécifiques se produisent.

Dans ce cas de figure, le webhook est défini côté fournisseur de sorte à envoyer une mise à jour à chaque fois qu'une personne requise signe un document. Après avoir consulté la documentation, nous savons que le chemin Json dans les données utiles est « event_name » et que la valeur à filtrer est « signer.done ». C'est pourquoi les valeurs suivantes sont entrées dans les colonnes correspondantes :

Chemin Json :

/event_name

Valeur attendue :

signer.done

Onglet Rechercher

Vous configurez sur cet onglet la recherche du document Therefore™ à mettre à jour. En chargeant un exemple de données utiles issues du fournisseur, vous pouvez sélectionner dans une liste la valeur unique à assigner. Dans ce cas de figure, la recherche est filtrée pour identifier l'unique ID du document du fournisseur qui correspondra à un document existant.

Valeur de la colonne Chaîne de recherche :

Json.GetValue("data.signature_request.id")

Onglet Mise à jour

Cet onglet permet de définir les valeurs issues des données utiles du webhook utilisées pour mettre à jour les champs de données d'index existants. Utilisez à cet effet un script ou des affectations.

Dans la présente configuration, le script affiché ci-dessous est utilisé. Plusieurs signataires d'un document sont identifiés à l'aide de leur adresse e-mail. En cas de correspondance de leur adresse e-mail, la colonne du champ de table « État du signataire » contient la valeur « Signé ».

var status = SourceIndexData.GetField("Status_Text"); 
var email = SourceIndexData.GetField("Email");
var email_update = Json.GetValue("data.signer.info.email")

for(var j = 0; j < email.length; j++)
{
    if(email[j] == email_update)
    {
        status[j] = "Signed";
    }
}
 
IndexData.SetField("Status_Text", status);

L'état du signataire est remplacé par « Signé » à chaque fois que le document est signé.

Informations complémentaires : Mises à jour multiples

Chaque webhook ne prend en charge qu'une seule action. Vous pouvez toutefois configurer un profil d’indexation qui permettra à Therefore™ Content Connector de mettre à jour les données d'index du document avec un autre état du signataire, selon les informations extraites des données utiles du webhook.

À titre d'exemple, vous pouvez utiliser le script suivant dans un profil d'indexation pour mettre à jour la colonne du champ de table « État du signataire » en remplaçant « En attente » par « Refusé » ou « Expiré ».

if(Signature.Status == "declined")

{

    Profile.NotApplicable();

}
 
var status = ExistingDoc.GetField("Status_Text");

var email = ExistingDoc.GetField("Email");
 
var signers = Signature.Signers;
 
for(var i = 0; i < signers.length; i++)

{

    for(var j = 0; j < email.length; j++)

    {

        if(email[j] == signers[i].SignerId)

        {

            if(signers[i] == "signer.done")    
            {    
                status[j] = "Signed";
            }
            else if (signers[i] == "signer.declined")
            {
                status[j] = "Declined";
            }
            else if (Signature.Status == "signature_request.expired")
            {
                status[j] = "Expired";
            }

        }

    }

}
 
IndexData.SetField("Status_Text", status);