Dokumentereignisse per Webhook an Ihr System senden
Ein Webhook sendet signiertes JSON an Ihre URL bei Versand, Öffnen, Unterschrift, Abschluss, Ablehnung, Ablauf oder Zurückziehen eines Dokuments. Erfordert Pro; Inhaber und Admins richten ihn ein.
Diese Übersetzung ist älter als der englische Artikel, daher können sich Details geändert haben. Englische Version lesen
Auf dieser Seite
Ein Webhook sendet jedes Mal eine Nachricht an eine URL von Ihnen, wenn mit einem Dokument etwas passiert, damit Ihr eigenes System darauf reagieren kann. Webhooks sind Teil von Pro: Sie funktionieren in einem Workspace, solange einer seiner Inhaber Pro hat, und nur Inhaber und Admins können sie verwalten. Jeder Workspace hat seine eigenen.
Webhook hinzufügen
- Öffnen Sie Einstellungen & Branding im Kontomenü und gehen Sie zu Integrationen.
- Drücken Sie Webhook hinzufügen.
- Geben Sie die Endpunkt-URL ein. Sie muss mit
https://beginnen und öffentlich sein: Adressen in privaten Netzwerken, die eigenen Adressen von Sealsimple und URLs mit Benutzername und Passwort werden abgelehnt. - Füllen Sie auf Wunsch Name aus, wählen Sie die Ereignisse (anfangs sind alle angekreuzt) und drücken Sie Webhook hinzufügen.
- Kopieren Sie den Signaturschlüssel, der erscheint, und drücken Sie Testereignis senden.
Ein Workspace kann bis zu 10 Webhooks haben.
Ereignisse
document.sent: Dokument gesendetdocument.viewed: Von einem Empfänger geöffnet, einmal pro Empfängerdocument.signed: Von einem Unterzeichner unterschrieben, einmal pro Unterzeichnerdocument.completed: Abgeschlossen: alle haben unterschriebendocument.declined: Abgelehntdocument.expired: Abgelaufendocument.canceled: Zurückgezogen
Was wir senden
Einen POST mit einem JSON-Body: id (bei jedem Versuch gleich, damit Sie Duplikate überspringen können), event, created_at, workspace_id, ein document mit id, title, status und url und bei Ereignissen zu einer einzelnen Person einen recipient mit name, email und role. Ein zurückgezogenes Dokument hat den Status voided. Das unterschriebene PDF selbst wird nicht gesendet. Das Testereignis hat das Ereignis test und ein erfundenes Dokument mit einem erfundenen Unterzeichner.
Signatur prüfen
Jede Anfrage hat einen Header Sealsimple-Signature wie t=1700000000,v1=…, neben Sealsimple-Event und Sealsimple-Delivery. So prüfen Sie ihn:
- Nehmen Sie den unveränderten Request-Body, genau so, wie er angekommen ist.
- Lesen Sie
t(eine Unix-Zeit in Sekunden) undv1aus dem Header. - Berechnen Sie den HMAC-SHA256 aus
t, einem Punkt und dem Body, mit Ihrem gesamten Signaturschlüssel als Schlüssel, als Hex in Kleinbuchstaben. - Akzeptieren Sie die Anfrage nur, wenn das Ergebnis
v1entspricht (vergleichen Sie in konstanter Zeit) undthöchstens ein paar Minuten alt ist.
Unter So verbinden Sie Ihr System zeigt Signatur prüfen (Node.js) das als Code, mit Code kopieren. Neuer Schlüssel ersetzt den Schlüssel sofort, aktualisieren Sie Ihre Prüfung also direkt danach.
Wiederholungen, das Protokoll und Pausieren
Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Andernfalls versuchen wir es später erneut, bis zu 6 Versuche insgesamt, verteilt über etwa einen Tag. Weiterleitungen folgen wir nicht, und eine Antwort mit 410 beendet die Versuche. Das Zustellprotokoll zeigt die letzten 50 Nachrichten mit der Antwort Ihres Endpunkts, und Erneut senden sendet eine davon erneut.
Nach 20 fehlgeschlagenen Zustellungen in Folge pausieren wir den Webhook (Nach Fehlern pausiert) und benachrichtigen die Inhaber des Workspaces per E-Mail. Beheben Sie das Problem am Endpunkt, schalten Sie den Webhook wieder ein und senden Sie aus dem Protokoll erneut, was Sie brauchen. Sie können einen Webhook auch mit seinem Schalter pausieren: Ereignisse, die während der Pause passieren, werden nicht nachträglich gesendet. Ohne Pro bleiben Webhooks bestehen, senden aber nichts.