Configurer des webhooks pour des mises à jour en temps réel avec Sign.Plus

Les webhooks vous permettent de recevoir des mises à jour en temps réel sur le statut de vos enveloppes dans Sign.Plus. Cet article vous guide à travers le processus de configuration et de traitement des webhooks pour votre intégration Sign.Plus.

Étape 1 : créer un webhook

Pour commencer à recevoir des mises à jour en temps réel, vous devez d'abord créer un webhook dans Sign.Plus. Voici comment procéder :

1. Choisissez une URL cible où vous souhaitez recevoir les notifications webhook. Il doit s'agir d'un point de terminaison sur votre serveur configuré pour traiter les requêtes POST entrantes.
2. Choisissez le ou les événements que vous souhaitez suivre. Sign.Plus propose les événements webhook suivants :
   • envelope_completed

      - Lorsqu'une enveloppe est complétée

   • envelope_expired

      - Lorsqu'une enveloppe expire

   • envelope_declined

      - Lorsqu'une enveloppe est refusée

   • envelope_voided

      - Lorsqu'une enveloppe est annulée

3. Utilisez l'API Sign.Plus pour créer le webhook. Vous devrez spécifier votre URL cible et le ou les événements que vous souhaitez suivre.

Pour des informations détaillées sur la création d'un webhook via l'API Sign.Plus, consultez la documentation du point de terminaison Create a webhook.

Étape 2 : traiter les notifications webhook

Une fois votre webhook configuré, Sign.Plus enverra des requêtes POST à l'URL que vous avez spécifiée chaque fois que les événements suivis se produiront. Voici ce que vous devez savoir sur le traitement de ces notifications :

1. Méthode de requête : Toutes les notifications webhook sont envoyées sous forme de requêtes HTTP 

   POST

   .

2. Structure du payload : Le payload du webhook est un objet JSON contenant deux sections principales :
   • hook

      : contient les métadonnées relatives au webhook lui-même.

   • data

      : contient les informations relatives à l'enveloppe ayant déclenché l'événement.

3. Exemples de payload : Voici des exemples de payloads pour différents événements :

   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Traitement de la notification : Lorsque votre serveur reçoit une notification webhook :
   • Vérifiez le payload pour vous assurer qu'il s'agit bien d'une notification webhook valide.
   • Extrayez les informations pertinentes du payload.
   • Effectuez les actions nécessaires en fonction du type d'événement (par exemple, mettre à jour votre base de données, notifier les utilisateurs, déclencher d'autres processus).

   • Envoyez une réponse 

     200 OK

      pour confirmer la réception du webhook.

Les webhooks de Sign.Plus ne seront envoyés qu'à partir des adresses IP autorisées suivantes :
34.65.253.117
34.65.146.131

Bonnes pratiques

1. Sécurité : assurez-vous que votre point de terminaison de webhook est sécurisé. Envisagez de mettre en place une authentification pour votre URL de webhook.
2. Idempotence : concevez votre gestionnaire de webhook pour qu'il soit idempotent. Cela signifie qu'il doit produire le même résultat même si le même webhook est reçu plusieurs fois.
3. Gestion des erreurs : mettez en place une gestion robuste des erreurs dans la logique de traitement de vos webhooks.

En suivant ce guide, vous serez en mesure de configurer et de gérer efficacement les webhooks, permettant à votre application de recevoir des mises à jour en temps réel sur le statut des enveloppes dans Sign.Plus.