Documentgebeurtenissen naar je systeem sturen met webhooks

Een webhook stuurt een ondertekend JSON-bericht naar je URL als een document is verstuurd, geopend, getekend, voltooid, geweigerd, verlopen of ingetrokken. Vereist Pro en een eigenaar of beheerder.

Deze vertaling is ouder dan het Engelse artikel, dus sommige details kunnen veranderd zijn. Lees de Engelse versie

Een webhook stuurt een bericht naar een URL van jou telkens als er iets met een document gebeurt, zodat je eigen systeem erop kan reageren. Webhooks horen bij Pro: ze werken in een werkruimte zolang een van de eigenaren Pro heeft, en alleen eigenaren en beheerders kunnen ze beheren. Elke werkruimte heeft eigen webhooks.

Een webhook toevoegen

  1. Open Instellingen en huisstijl in het accountmenu en ga naar Integraties.
  2. Druk op Webhook toevoegen.
  3. Vul de Endpoint-URL in. Die moet beginnen met https:// en openbaar zijn: adressen in privénetwerken, adressen van Sealsimple zelf en URL's met een gebruikersnaam en wachtwoord worden geweigerd.
  4. Voeg als je wilt een Naam toe, kies de Gebeurtenissen (in het begin zijn ze allemaal aangevinkt) en druk op Webhook toevoegen.
  5. Kopieer de Ondertekeningssleutel die verschijnt, en druk op Testgebeurtenis sturen.

Een werkruimte kan maximaal 10 webhooks hebben.

Gebeurtenissen

  • document.sent: Document verstuurd
  • document.viewed: Geopend door een ontvanger, één keer per ontvanger
  • document.signed: Ondertekend door een ondertekenaar, één keer per ondertekenaar
  • document.completed: Voltooid: iedereen heeft ondertekend
  • document.declined: Geweigerd
  • document.expired: Verlopen
  • document.canceled: Ingetrokken

Wat we sturen

Een POST met een JSON-body: id (bij elke poging hetzelfde, zodat je dubbele berichten kunt overslaan), event, created_at, workspace_id, een document met id, title, status en url, en bij gebeurtenissen over één persoon een recipient met name, email en role. Een ingetrokken document heeft de status voided. De ondertekende PDF zelf wordt niet meegestuurd. De testgebeurtenis heeft het event test en een verzonnen document en ondertekenaar.

De handtekening controleren

Elk verzoek heeft een header Sealsimple-Signature zoals t=1700000000,v1=…, naast Sealsimple-Event en Sealsimple-Delivery. Zo controleer je hem:

  1. Neem de onbewerkte request-body, precies zoals die binnenkwam.
  2. Lees t (een Unix-tijd in seconden) en v1 uit de header.
  3. Bereken de HMAC-SHA256 van t, een punt en de body, met je volledige ondertekeningssleutel als sleutel, in hexadecimale kleine letters.
  4. Accepteer het verzoek alleen als dit gelijk is aan v1 (vergelijk in constante tijd) en t hooguit een paar minuten oud is.

Onder Zo koppel je het toont De handtekening controleren (Node.js) dit als code, met Code kopiëren. Nieuwe sleutel vervangt de sleutel meteen, dus werk je controle direct daarna bij.

Nieuwe pogingen, het logboek en pauzeren

Antwoord binnen 10 seconden met een 2xx-status. Anders proberen we het later opnieuw, tot 6 pogingen in totaal, verspreid over ongeveer een dag. Doorverwijzingen worden niet gevolgd, en een antwoord 410 stopt de pogingen. Het Bezorglogboek toont de laatste 50 berichten met het antwoord van je endpoint, en Opnieuw sturen verstuurt er een opnieuw.

Na 20 mislukte bezorgingen achter elkaar pauzeren we de webhook (Gepauzeerd na fouten) en mailen we de eigenaren van de werkruimte. Herstel het endpoint, zet de webhook weer aan en verstuur opnieuw wat je nodig hebt vanuit het logboek. Je kunt een webhook ook pauzeren met de schakelaar: gebeurtenissen die plaatsvinden terwijl hij gepauzeerd is, worden later niet alsnog verstuurd. Zonder Pro blijven webhooks bestaan, maar sturen ze niets.

Was dit artikel nuttig?

Probeer het met je volgende overeenkomst.

Elke kalendermaand 5 documenten gratis versturen. Geen creditcard nodig.

Nog steeds hulp nodig?

Vraag het onze assistent in de chat: die antwoordt meteen. Of mail ons, dan antwoordt een mens binnen één werkdag.