Notifier mon application avec les webhooks

Afin de notifier votre application des différents statuts et étapes d'une procédure de signature, nous mettons à disposition une notification dite de serveur à serveur avec les webhooks.

Les webhooks seront définis au moment de créer la procédure de signature dans la partie "config" pour les actions suivantes :

• "procedure.started" :
  • Déclenché au moment où la procédure est rendu active (plus considérée comme étant un brouillon)
• "procedure.finished" :
  • Déclenché lorsque tous les membres de la procédure de signature sont intervenus.
• "procedure.refused" :
  •  Déclenché lorsque la procédure de signature est refusée par l'un des membres.
  • Le commentaire de refus sera retourné dans la partie brute ("raw") de la réponse API.
• "member.started" :
  • Déclenché lorsqu'un membre doit intervenir sur la procédure de signature. Ceci ne signifie pas que le signataire a ouvert la procédure mais uniquement que c'est à son tour de réaliser une action (généralement signer ou valider la procédure).
• "member.finished" :
  • Déclenché lorsque le membre a terminé son action.
• "comment.created" :
  • Déclenché lorsqu'un commentaire est laissé sur la procédure.
  • Note: Option non disponible pour le moment dans l'interface de signature.

Chaque webhook sera composé de la façon suivante :

{
    "url": "https://hookb.in/v3oopq0b",
    "method": "GET",
    "headers": {
        "X-Yousign-Custom-Header": "Test value"
    }
}

• "url" :
  • Il s'agit de l'URL que Yousign notifiera.
  • Cette URL doit être accessible publiquement, ou tout du moins accessible par les serveurs de Yousign (sans protection ni mot de passe). Pour des raisons de sécurité, seul un filtrage par adresse IP peut être établi avec la plage d'adresses IP publiques de Yousign.
  • L'URL peut être en HTTP ou HTTPS (uniquement avec un certificat valide dans le cadre de l'utilisation de HTTPS).
  • Vous pouvez également notifier une API interne à votre application au lieu d'une page web à l'aide de la méthode POST.
  • Seuls les paramètres de cette URL sont à encoder en respectant les règles d'encodage W3C
    • Exemple : https://mon-url.com/procedure.started?param=internalId%3D123
    • Avec "param" en key et "internalId=123" en valeur

• "method" :
  • GET (valeur par défaut)
  • POST
  • PUT
  • PATCH
  • Et le contenu envoyé par Yousign sera toujours identique quelque soit le verbe HTTP employé.

• "headers" :
  • Permet de passer un certain nombre d'informations internes à la société ou à l'application (identifiant interne de facture, identifiant de contrat, etc...)
  • Principe de clé / valeur HTTP
  • Erreur dans la documentation : Y-Yousign ==> X-Yousign et donc "X-..." peut être personnalisé comme souhaité.

 Voici un exemple de webhook pour "procedure.started" :

Codes retour acceptés :

200, // OK
201, // Created
202, // Accepted
204, // No Content

Voici quelques outils gratuits permettant de tester la bonne réception des webhooks sans faire de code : Hookbin et Requestb.in

Auto-retry sur les webhooks

Si votre infrastructure ou service n'est pas accessible au moment de l'envoi des webhooks par Yousign, alors nous mettons en place un système de relances automatiques.

Fréquences des relances automatiques effectuées par Yousign

Exemples :