Webhookuri: evenimentele documentelor în sistemul dvs.
Un webhook trimite la URL-ul dvs. un mesaj JSON semnat când un document este trimis, deschis, semnat, finalizat, refuzat, expirat sau anulat. Necesită Pro; configurat de proprietari și administratori.
Această traducere este mai veche decât articolul în engleză, așa că unele detalii s-ar putea să se fi schimbat. Citiți versiunea în engleză
Pe această pagină
Un webhook trimite un mesaj la un URL al dvs. de fiecare dată când se întâmplă ceva cu un document, ca propriul sistem să poată reacționa. Webhookurile fac parte din Pro: funcționează într-un spațiu de lucru cât timp unul dintre proprietarii lui are Pro și doar proprietarii și administratorii le pot gestiona. Fiecare spațiu de lucru are propriile webhookuri.
Adăugați un webhook
- Deschideți Setări și branding din meniul contului și mergeți la Integrări.
- Apăsați Adăugați un webhook.
- Introduceți URL-ul endpointului. Trebuie să înceapă cu
https://și să fie public: adresele din rețele private, adresele Sealsimple și URL-urile cu nume de utilizator și parolă sunt refuzate. - Dacă doriți, adăugați un Nume, alegeți Evenimente (la început sunt bifate toate) și apăsați Adăugați webhookul.
- Copiați cheia afișată la Cheie secretă de semnare și apăsați Trimiteți un eveniment de test.
Un spațiu de lucru poate avea cel mult 10 webhookuri.
Evenimente
document.sent: Document trimisdocument.viewed: Deschis de un destinatar, o dată pentru fiecare destinatardocument.signed: Semnat de un semnatar, o dată pentru fiecare semnatardocument.completed: Finalizat: au semnat toțidocument.declined: Refuzatdocument.expired: Expiratdocument.canceled: Anulat
Ce trimitem
O cerere POST cu un corp JSON: id (același la fiecare încercare, ca să puteți sări peste dubluri), event, created_at, workspace_id, un document cu id, title, status și url, iar pentru evenimentele despre o singură persoană, un recipient cu name, email și role. Un document anulat are starea voided. PDF-ul semnat în sine nu este trimis. Evenimentul de test are evenimentul test, un document și un semnatar fictivi.
Verificați semnătura
Fiecare cerere are un antet Sealsimple-Signature de forma t=1700000000,v1=…, alături de Sealsimple-Event și Sealsimple-Delivery. Pentru a o verifica:
- Luați corpul brut al cererii, exact așa cum a sosit.
- Citiți din antet
t(un timp Unix în secunde) șiv1. - Calculați HMAC-SHA256 pentru
t, un punct și corpul cererii, cu întreaga cheie secretă de semnare drept cheie, în hexazecimal cu litere mici. - Acceptați cererea doar dacă rezultatul este egal cu
v1(comparați în timp constant) și dacătare cel mult câteva minute.
La Cum vă conectați, Verificați semnătura (Node.js) arată acest lucru sub formă de cod, cu Copiați codul. Cheie nouă înlocuiește imediat cheia secretă, așa că actualizați verificarea imediat după aceea.
Reîncercări, jurnalul și întreruperea
Răspundeți cu un status 2xx în 10 secunde. Altfel, încercăm din nou mai târziu, până la 6 încercări în total, pe parcursul a aproximativ o zi. Redirecționările nu sunt urmate, iar un răspuns 410 oprește încercările. Jurnal de livrări arată ultimele 50 de mesaje, cu răspunsul endpointului dvs., iar Retrimiteți trimite din nou unul dintre ele.
După 20 de livrări eșuate la rând, întrerupem webhookul (Întrerupt după erori) și le trimitem un e-mail proprietarilor spațiului de lucru. Reparați endpointul, reactivați webhookul și retrimiteți din jurnal ce aveți nevoie. Puteți întrerupe și singur un webhook, cu comutatorul lui: evenimentele care au loc cât timp este întrerupt nu sunt trimise ulterior. Fără Pro, webhookurile rămân, dar nu trimit nimic.