Mise en place de webhooks pour les mises à jour en temps réel de Sign.Plus

Les Webhooks vous permettent de recevoir des mises à jour en temps réel sur l'état de vos enveloppes dans le Sign.Plus. Cet article vous guidera dans la mise en place et la gestion de 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 le Sign.Plus. Voici comment :

1. Décidez d'une URL cible où vous souhaitez recevoir des notifications sur le webhook. Ceci devrait être un point de terminaison sur votre serveur qui est configuré pour gérer les requêtes POST entrantes.
2. Choisissez le(s) événement(s) que vous souhaitez suivre. Sign.Plus propose les événements webhook suivants :
   • envelope_completed - Quand une enveloppe est terminée
   • envelope_expired - Quand une enveloppe est expirée
   • envelope_declined - Quand une enveloppe est refusée
   • envelope_voided - Quand 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(s) événement(s) que vous souhaitez suivre.

For detailed information on how to create a webhook using the Sign.Plus API, refer to the Create a webhook endpoint documentation.

Étape 2 : Gérer les notations de webhook

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

1. Méthode de requête : Toutes les notifications de webhook sont envoyées sous forme de requêtes HTTP POST.
2. Structure de charge utile : La charge utile du webhook est un objet JSON contenant deux sections principales :
   • hook: Contient des métadonnées sur le webhook lui-même.
   • data: Contains information about the envelope that triggered the event.
3. Exemples de charge utile : 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",
"événement": "enveloppe_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",
"événement": "enveloppe_expiré",
"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",
"événement": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Handling the Notification: When your server receives a webhook notification:
   • Vérifiez la charge utile pour vous assurer qu'il s'agit d'une notification de webhook valide.
   • Extraire les informations pertinentes de la charge utile.
   • Effectuer toutes 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éponse200 OKpour confirmer la réception du webhook.

Meilleures pratiques

1. Sécurité : Assurez-vous que votre point de terminaison du webhook est sécurisé. Envisagez l'implémentation de l'authentification pour votre URL webhook.
2. Idempotency: Concevez votre gestionnaire de webhook pour être idémpotent. Cela signifie qu'il devrait produire le même résultat même si le même webhook est reçu plusieurs fois.
3. Gestion des erreurs : Implémenter une gestion robuste des erreurs dans votre logique de traitement de webhook.

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 l'état de l'enveloppe dans le panneau. lus.