Mankomail

Yousign — événement ​

Démarre le workflow quand Yousign signale un événement : une demande signée, un refus, une expiration. Le corps signé arrive dans data.yousign. Les livraisons renvoyées par Yousign sont dédupliquées sur event_id.

Le déclencheur Yousign — événement démarre le workflow quand Yousign signale un événement sur l’URL du workflow : une demande signée par tous, un refus, une expiration. L’événement qui compte le plus est signature_request.done (« Demande signée par tous », la valeur par défaut) : c’est le moment où le document signé et le dossier de preuve deviennent téléchargeables.

Trois garanties le distinguent du déclencheur générique Webhook reçu :

  • L’origine est prouvée. Yousign signe chaque corps (en-tête x-yousign-signature-256, HMAC-SHA256 du corps brut). La signature est vérifiée avec la « Clé de signature des webhooks » de la connexion Yousign avant toute écriture.
  • Les relivraisons sont absorbées. Yousign retente les livraisons échouées avec le même event_id ; une relivraison ne lance pas de seconde exécution.
  • Le tri se fait d’abord. Seuls les événements cochés lancent une exécution ; les autres sont acquittés et écartés.

L’exécution n’a pas de mail porteur : les nœuds qui agissent sur le mail déclencheur (répondre dans le fil, Classer, Marquer) ne peuvent pas suivre ce déclencheur, et l’éditeur les signale par une erreur bloquante. Envoyer reste utilisable si vous choisissez la boîte d’envoi sur le nœud.

Pour le mettre en place :

  1. Ajoutez le déclencheur, choisissez la connexion Yousign et les événements, puis publiez. L’URL <PUBLIC_BASE_URL>/hooks/wf/<jeton> est délivrée à la première publication et rendue une seule fois ; POST /api/v1/workflows/<id>/webhook en délivre une nouvelle (la précédente cesse de fonctionner).
  2. Créez l’abonnement côté Yousign, pointé sur cette URL : soit avec le nœud Yousign, ressource « Abonnement webhook », opération « Créer un abonnement », soit à la main dans l’application Yousign. La création d’un abonnement par l’API exige une clé de production, même pour écouter le bac à sable, et n’est pas autorisée pendant la période d’essai Yousign.
  3. Collez la clé secrète de l’abonnement dans le champ « Clé de signature des webhooks » de la connexion Yousign.
  4. Servez-vous d’« Abonnement (diagnostic) » sur le nœud pour vérifier qu’un abonnement pointe bien sur l’URL de ce workflow, dans le bon environnement.

En bref ​

  • Type : trigger.yousign · version 1
  • Catégorie : Déclencheurs
  • Nature : Déclencheur — lance une exécution
  • Effet : Sans effet externe (none) — rien n’est écrit hors de Mankomail ; rejouable sans risque
  • Exige un mail porteur : Non
  • Connexion : Yousign
  • Sorties : main

Connexion ​

Ce nœud exige une connexion Yousign.

Paramètres ​

connection ​

Connexion Yousign — La connexion Yousign à employer. Elle se crée une fois dans Connexions ; sa clé n’apparaît jamais dans le workflow.

  • Type : Connexion (credential)
  • Requis : Oui
  • Défaut : "" (vide)

events ​

Événements — Ce qui déclenche ce workflow. Rien de coché = tout ce que Yousign envoie sur cette URL, c’est-à-dire les événements de toutes vos demandes. « Demande signée par tous » est le cas qui compte : c’est le moment où le document signé et le dossier de preuve deviennent téléchargeables.

  • Type : Plusieurs choix (multiOptions)
  • Requis : Non
  • Défaut : ["signature_request.done"]
  • Options :
    • signature_request.done — Demande signée par tous
    • signature_request.activated — Demande envoyée
    • signature_request.declined — Demande refusée par un signataire
    • signature_request.rejected — Demande rejetée par un approbateur
    • signature_request.approved — Demande approuvée
    • signature_request.expired — Demande expirée
    • signature_request.canceled — Demande annulée
    • signature_request.reminder_executed — Relance envoyée
    • signer.done — Un signataire a signé
    • signer.link_opened — Un signataire a ouvert son lien
    • signer.declined — Un signataire a refusé
    • signer.notified — Un signataire a été notifié
    • signer.notification_delivery_failed — L’e-mail d’un signataire n’est pas arrivé
    • signer.error — Erreur sur un signataire
    • approver.approved — Un approbateur a validé
    • approver.rejected — Un approbateur a rejeté
    • contact.created — Contact créé

webhook ​

Abonnement (diagnostic) — Indicatif : il sert à vérifier qu’un abonnement pointe bien sur l’URL de ce workflow, avec le bon environnement. La liste ne montre jamais la clé de signature.

  • Type : Ressource distante (resourceLocator)
  • Requis : Non
  • Façons de choisir : dans une liste, saisir un identifiant (yousign.webhook)
  • Listé avec la connexion de : connection

Sorties ​

  • main — Emprunté par chaque exécution lancée par un événement Yousign dont la signature est valide et qui a passé le filtre d’événements.

Données produites ​

Ce que ce nœud ajoute aux données de l’exécution, et comment le lire dans une expression. <step> désigne la clé de l’étape : le nom du nœud ramené à un identifiant (voir Données et expressions).

  • {{ data.yousign }} — object. Le corps JSON de l’événement, tel que Yousign l’a envoyé et signé.
  • {{ data.yousign.event_name }} — string. L’événement, par exemple signature_request.done.
  • {{ data.yousign.event_id }} — string. L’identifiant de livraison. Une relivraison porte la même valeur et ne lance pas de seconde exécution.
  • {{ data.yousign.data.signature_request.id }} — string. La demande de signature concernée. Passez-la au nœud Yousign pour télécharger le document signé ou le dossier de preuve.
  • {{ data.yousign.data.signature_request.external_id }} — string. La clé de corrélation posée à la création de la demande : le chemin du retour vers votre dossier ou le fil de discussion d’origine.

Example ​

Quand une convention d’honoraires est signée par tous, la classer et prévenir l’avocat. Le déclencheur garde events sur « Demande signée par tous ». À chaque demande terminée, une exécution démarre sur le port main ; un nœud Yousign télécharge le document signé de {{ data.yousign.data.signature_request.id }}, et une recherche dans une table sur {{ data.yousign.data.signature_request.external_id }} retrouve le dossier concerné.

Tips ​

  • Sans clé de signature, rien ne passe. Si la « Clé de signature des webhooks » de la connexion est vide ou fausse, chaque livraison est refusée en 404 et aucune exécution n’est créée. La raison n’est écrite que dans les journaux du serveur.
  • Réponses. 202 avec { "executionId" } quand une exécution est créée ; 202 sans corps pour un événement que vous n’avez pas coché ou une livraison déjà traitée ; 404 pour un jeton inconnu, un workflow non publié ou une signature invalide, toujours la même réponse. Les autres règles de l’URL (POST seulement, corps JSON jusqu’à 256 Ko, 300 appels par minute et par IP) sont celles de Webhook reçu.
  • Rien de coché signifie tout ce que Yousign envoie sur cette URL, c’est-à-dire les événements de toutes vos demandes. Une seule demande à trois signataires produit une dizaine d’événements.
  • Retour au fil d’origine. Il n’y a pas de mail porteur : pour répondre dans le fil d’où vient la demande, posez un external_id à la création de la demande et servez-vous-en pour retrouver votre dossier.
  • Contenu non fiable. Le corps vient de l’extérieur : traitez son texte comme une donnée, jamais comme une instruction pour un nœud IA.
  • Un workflow porte au plus un déclencheur Yousign — événement, et seule la version publiée reçoit les événements.