Webhooks : envoyer les événements à votre système

Un webhook envoie un message JSON signé à votre URL quand un document est envoyé, ouvert, signé, finalisé, refusé, expiré ou annulé. Nécessite Pro ; configuré par les propriétaires et administrateurs.

Un webhook envoie un message à une URL qui vous appartient chaque fois qu'il se passe quelque chose sur un document, pour que votre propre système puisse réagir. Les webhooks font partie de Pro : ils fonctionnent dans un espace de travail tant que l'un de ses propriétaires a Pro, et seuls les propriétaires et les administrateurs peuvent les gérer. Chaque espace de travail a les siens.

Ajouter un webhook

  1. Ouvrez Paramètres et image de marque dans le menu du compte et allez dans Intégrations.
  2. Cliquez sur Ajouter un webhook.
  3. Saisissez l'URL de l'endpoint. Elle doit commencer par https:// et être publique : les adresses de réseaux privés, les adresses de Sealsimple lui-même et les URL contenant un nom d'utilisateur et un mot de passe sont refusées.
  4. Ajoutez un Nom si vous le souhaitez, choisissez les Événements (tous sont cochés au départ) et cliquez sur Ajouter le webhook.
  5. Copiez le Secret de signature qui s'affiche, puis cliquez sur Envoyer un événement de test.

Un espace de travail peut avoir jusqu'à 10 webhooks.

Événements

  • document.sent : Document envoyé
  • document.viewed : Ouvert par un destinataire, une fois par destinataire
  • document.signed : Signé par un signataire, une fois par signataire
  • document.completed : Finalisé : tout le monde a signé
  • document.declined : Refusé
  • document.expired : Expiré
  • document.canceled : Annulé

Ce que nous envoyons

Une requête POST avec un corps JSON : id (le même à chaque essai, pour que vous puissiez ignorer les doublons), event, created_at, workspace_id, un document avec id, title, status et url, et, pour les événements qui concernent une personne, un recipient avec name, email et role. Un document annulé a le statut voided. Le PDF signé lui-même n'est pas envoyé : récupérez-le avec l'API REST une fois le document finalisé. L'événement de test a pour événement test, avec un document et un signataire fictifs.

Vérifier la signature

Chaque requête contient un en-tête Sealsimple-Signature de la forme t=1700000000,v1=…, à côté de Sealsimple-Event et Sealsimple-Delivery. Pour la vérifier :

  1. Prenez le corps brut de la requête, exactement tel qu'il est arrivé.
  2. Lisez t (un horodatage Unix en secondes) et v1 dans l'en-tête.
  3. Calculez le HMAC-SHA256 de t, d'un point et du corps, avec votre secret de signature complet comme clé, en hexadécimal minuscule.
  4. N'acceptez la requête que si le résultat est égal à v1 (comparez en temps constant) et que t date de quelques minutes au plus.

Sous Comment connecter vos outils, Vérifier la signature (Node.js) montre cela sous forme de code, avec Copier le code. Nouveau secret remplace le secret immédiatement : mettez donc à jour votre vérification juste après.

Nouvelles tentatives, journal et mise en pause

Répondez avec un statut 2xx en moins de 10 secondes. Sinon, nous réessayons plus tard, jusqu'à 6 essais au total sur environ une journée. Les redirections ne sont pas suivies, et une réponse 410 arrête les essais. Le Journal des envois affiche les 50 derniers messages avec la réponse de votre endpoint, et Renvoyer en renvoie un.

Après 20 échecs d'envoi consécutifs, nous mettons le webhook en pause (En pause après des échecs) et envoyons un e-mail aux propriétaires de l'espace de travail. Réparez l'endpoint, réactivez le webhook et renvoyez depuis le journal ce dont vous avez besoin. Vous pouvez aussi mettre un webhook en pause avec son interrupteur : les événements qui surviennent pendant la pause ne sont pas envoyés plus tard. Sans Pro, les webhooks restent mais n'envoient rien.

Existe-t-il une API ?

Oui, avec Pro. Les webhooks préviennent votre système quand quelque chose se passe ; l'API REST lui permet d'agir : importer et envoyer des documents, puis récupérer leur statut, le PDF signé et la piste d'audit. Commencez par Utiliser l'API (en anglais), ou consultez tous les endpoints dans la documentation de l'API (en anglais).

Cet article vous a-t-il été utile ?

Essayez avec votre prochain contrat.

5 envois gratuits chaque mois civil. Sans carte bancaire.

Besoin d'aide supplémentaire ?

Posez votre question à notre assistant dans le chat : il répond tout de suite. Ou écrivez-nous, et une personne vous répondra sous un jour ouvré.