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
Op deze pagina
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
- Open Instellingen en huisstijl in het accountmenu en ga naar Integraties.
- Druk op Webhook toevoegen.
- 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. - Voeg als je wilt een Naam toe, kies de Gebeurtenissen (in het begin zijn ze allemaal aangevinkt) en druk op Webhook toevoegen.
- Kopieer de Ondertekeningssleutel die verschijnt, en druk op Testgebeurtenis sturen.
Een werkruimte kan maximaal 10 webhooks hebben.
Gebeurtenissen
document.sent: Document verstuurddocument.viewed: Geopend door een ontvanger, één keer per ontvangerdocument.signed: Ondertekend door een ondertekenaar, één keer per ondertekenaardocument.completed: Voltooid: iedereen heeft ondertekenddocument.declined: Geweigerddocument.expired: Verlopendocument.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:
- Neem de onbewerkte request-body, precies zoals die binnenkwam.
- Lees
t(een Unix-tijd in seconden) env1uit de header. - Bereken de HMAC-SHA256 van
t, een punt en de body, met je volledige ondertekeningssleutel als sleutel, in hexadecimale kleine letters. - Accepteer het verzoek alleen als dit gelijk is aan
v1(vergelijk in constante tijd) enthooguit 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.