Zum Hauptinhalt springen

Webhooks auf Legalesign

Was sind Webhooks​

Webhooks sind Ihre URLs, an die Legalesign Echtzeit-Statusaktualisierungen sendet. Sie können eigene URLs erstellen oder Automatisierungssysteme (wie MS Power Automate) können sie generieren, um einen Workflow zu starten.

Zum Beispiel erstellen wir in dieser Demo eine URL mit Microsoft Power Automate. Wir fügen diese URL als Webhook in Legalesign hinzu, wenn Dokumente unterschrieben werden. Der Power Automate-Fluss wird ausgelöst, wenn ein Dokument unterschrieben wird, und speichert diese neu unterschriebenen PDFs automatisch in Sharepoint. Erfahren Sie mehr über MS Power Automate.

Info

Wichtiger Hinweis – Sie müssen Team-Admin-Berechtigungen haben, um Teamereignisse an Ihren Webhook senden zu lassen.

Warum Sie Webhooks benötigen​

Webhooks ermöglichen es Ihnen, ein ereignisgesteuertes System zu pflegen. Webhooks informieren Sie über alle Ereignisse in Ihren Gruppen. Sie könnten sie verwenden, um Ihr eigenes Live-Dashboard zu erstellen und/oder um mit Ihrer eigenen Datenbank zu synchronisieren.

Wie oben erwähnt, ermöglichen generierte Webhooks von Automatisierungssystemen wie Power Automate, Speicherprozesse, E-Mails, Aufzeichnung usw. zu starten. In Kombination mit der API bietet dies alles, was Sie für die Prozessautomatisierung benötigen.

Echtzeit-Alternative Websocket

Eine Echtzeit-Websocket-Abonnementquelle ist ebenfalls verfügbar. Dies kann besser geeignet sein, wenn Sie clientseitige Live-Updates wünschen, ohne einen Webhook-Endpunkt offenzulegen. Das Websocket bietet eine breitere Palette von Ereignissen als Webhooks.

Siehe: Echtzeit-Websocket Schnellstart

Tipp

Ja, Webhooks fühlen sich umständlich an, aber sie lohnen sich sehr und sind großartig für Ihre Integration. Lesen Sie weiter.

Arten von Webhooks​

  • Echtzeit-Ereignisse
  • Alle Ereignisse alle 6 Minuten (Legacy)
  • Bei [Ereignis] (Legacy)

Für Legacy-Webhooks siehe: Legacy-Webhooks

Info

Webhooks werden am häufigsten zum Herunterladen eines unterschriebenen PDFs verwendet. Wenn Sie den Webhook erstellen, wenden Sie den Ereignisfilter „Final PDF created“ an. Im Code ist das eingehende request.body JSON, parsen Sie es und extrahieren Sie documentId = ['data']['uuid']. Jetzt führen Sie die API-Anfrage zum Herunterladen des PDFs aus – GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.

Wie man einen Webhook hinzufügt oder entfernt​

Webhook hinzufügen oder entfernen über die Web-App​

Gehen Sie zum API-Dashboard und navigieren Sie zum Abschnitt Webhooks. Das Formular verfügt über einfache Steuerelemente zum Hinzufügen oder Entfernen von Webhooks. Sie können optional Webhook-Ereignisse auf bestimmte Teams und/oder Ereignisse beschränken.

Screenshot des Webhooks-Bereichs

Gefahr

Ihre Webhooks erhalten Ereignisse von allen Konten, bei denen Sie Admin sind, sowohl Entwicklung als auch Produktion. Verwenden Sie den Gruppenfilter, um verschiedene Webhooks für Ihre verschiedenen Gruppen zu erstellen.

Webhook hinzufügen oder entfernen über die REST API​

Siehe den Abschnitt „webhook“ am unteren Rand der linken Navigation innerhalb der API-Dokumentation: REST API Webhooks

Webhook hinzufügen oder entfernen über GraphQL​

Neu! Im Legalesign GraphiQL Explorer, angemeldet mit Ihrem Legalesign-Konto, haben Sie vollständige CRUD-Rechte über Webhooks. Webhooks können als Attribut des Benutzertyps aufgelistet werden, und es gibt Mutations zum Erstellen, Aktualisieren und Löschen von Webhooks.

Was ist in einem Webhook enthalten?​

Die schnellste Möglichkeit, Ihre Daten zu überprüfen, besteht darin, einen Webhook hinzuzufügen, einige Testdokumente in der Web-App zu senden/unterschreiben/ablehnen und dann die Webhook-Protokolle im Legalesign API-Dashboard anzusehen.

Wenn Sie eine temporäre Webhook-URL zum Testen benötigen, schauen Sie sich ngrok an.

Kurzanleitung zu ngrok: Sobald Sie ngrok heruntergeladen haben, starten Sie es im Terminal mit ./ngrok http 80, und es gibt Ihnen eine https-Adresse. Geben Sie diese als Ihren Webhook ein. Öffnen Sie nun http://127.0.0.1:4040. Das war’s, Sie sehen alle Webhooks und ihre Daten. Beginnen Sie mit dem Senden und Unterschreiben von Testdokumenten. Hinweis: Ngrok kann einen 5XX-Fehler zurückgeben, sodass Sie mehrere Versuche und Fehlermeldungen erwarten können, da das System den 5XX-Status als fehlgeschlagenen Versuch betrachtet.

Info

Stellen Sie sicher, dass Ihr empfangender Webhook-Code eine 2XX-Erfolgsantwort zurückgibt. Wenn Sie mehrere mögliche Ausnahmen in Ihrem Code haben, geben Sie verschiedene 5XX-Statuscodes zurück. Die Webhook-Protokolle im API-Dashboard zeigen dann an, welche Ausnahme ausgelöst wurde.

Das Format des Echtzeit-Webhooks​

Das Datenformat kann eines von zwei Schemas sein, entweder ein „document“-Schema oder ein „recipient“-Schema. Prüfen Sie das Attribut „object“, um zu bestimmen, mit welchem Schema Sie es zu tun haben.

Beide Schemata haben auch ein „event“-Attribut. Sie können beim Erstellen des Webhooks nach Objekt und optional Ereignis filtern.

Eine Tabelle aller möglichen Objekte und Ereignisse finden Sie unten. Dieses Bild veranschaulicht ein Dokumentobjekt (für ein „created“-Ereignis). Die vollständigen JSON-Schemata sind am Ende dieses Artikels angehängt.

Dokumentdaten in ngrok

Anfragen werden als POST-Anfrage mit JSON gesendet. Bitte beachten Sie, dass sich der Inhalt von „data“ im Laufe der Zeit mit weiteren Feldern erweitern kann.

Tipp

Verwenden Sie „tag“-Attribute. Sie können beim Erstellen eines Dokuments bis zu 3 Tags setzen. Durch die Verwendung von Tags müssen Sie möglicherweise keine Legalesign-IDs speichern. Sie können auch ein Tag verwenden, um ein Geheimnis zu speichern, um die eingehende Anfrage zu verifizieren (Danke an Themis für diese Anregung).

Tabelle möglicher Kombinationen von „object“ und „event“:

ObjektEreignis
documentcreated
documentrejected
documentfinalPdfCreated
recipientcompleted
recipientrejected
recipientemailOpened
recipientvisiting
recipientbounced
recipientautoReminderEmail
recipientemailNotification

Die meisten Ereignisse treten nur einmal auf. Ausnahmen sind visiting, bounced, emailNotification und autoReminderEmail, die mehrmals auftreten können.

Warnung

Vergessen Sie nicht, den CSRF-Schutz für Ihre Ansicht, die diese POST-Anfragen empfängt, auszuschalten.

Hier ist ein Beispiel für ein „recipient“-Objekt mit dem Ereignis „bounced“:

Empfängerdaten in ngrok

Beachten Sie emailBounce und emailBounceMessage in „data“. „emailBounceMessage“ zeigt die Art des Bounce wie folgt an:

  • Hard Bounce: „Message hard bounced“
  • Soft Bounce: „Email soft bounced (either out of office or a timeout)“
  • Verzögert: „Message delayed (check email domain exists)“
Info

Das Schema kann jederzeit neue Attribute hinzugefügt bekommen.

Webhooks im API-Dashboard debuggen​

Alle Webhooks werden protokolliert und Sie können deren Inhalt und den HTTP-Statuscode in Ihrem API-Dashboard prüfen. Weitere Informationen finden Sie im Dashboard-Tutorial

Manueller Webhook-Auslöser​

Lösen Sie manuell einen Webhook mit dem Formular am Ende der Webhooks-Seite in Ihrem Developer Portal aus.

Stellen Sie sicher, dass Sie eine echte Empfänger- oder Dokument-ID verwenden, abhängig vom Ereignis.

Statuscodes​

Klicken Sie auf diese Links, um die Referenztabelle für Dokumentenstatus und Empfängerstatus zu sehen.

Einen Webhook verifizieren​

Der Webhook signiert das Datenpaket mit einem privaten Schlüssel. Sie können dies mit dem öffentlichen Schlüssel verifizieren – öffentlichen Schlüssel herunterladen.

  • Der Ort des Signaturstrings befindet sich im Header X-Signed-SHA256.
  • Die signierten Daten sind der gesamte request.body (als String).

Die „Signatur“ ist base64-codiert. Hier ist Beispielverifizierungscode in node.js:

const crypto = require('crypto');
const fs = require('fs');

const cert = fs.readFileSync('/location/of/downloadedCert.crt', 'utf8');
const c = new crypto.X509Certificate(cert);
const k = c.publicKey
let verifier = crypto.createVerify('SHA256');
let rawdata = 'sentdata' //JSON stringify data in request.body
let sha256signature = 'xxx' //value of 'X-Signed-Sha256' request header.
verifier.update(rawdata);
return verifier.verify(k, sha256signature, 'base64');

[1]

Optionale HMAC-basierte Verifizierung ist ebenfalls verfügbar. Für HMAC wird Ihnen ein geheimer Schlüssel für Ihre Webhooks mitgeteilt. Der signierte Wert wird im Header X-HMAC-SHA256 ankommen.

Es gibt viele Online-Ressourcen, die zeigen, wie man einen HMAC-Wert verifiziert. Beispiel für eine Verifizierung in Python wäre:

import hmac, hashlib
sentdata = 'sentdata' # JSON stringify data in request.body
hmacvalue = 'xxx' # value of 'X-HMAC-Sha256' in request header.
v = hmac.new('your secret value'.encode(), 'sentdata'.encode(), hashlib.sha256)
isValid = v.hexdigest() == hmacvalue

Oder Beispielcode für Salesforce Apex zur Verifizierung eines HMAC ist:

String message = 'JSONstring'; //sent in request.body
String privatekey = 'privateKey'; //shared value you have been given
String hmacvalue = 'xxx'; //value of 'X-HMAC-Sha256' in request header.
Boolean verified = Crypto.verifyHMac('HmacSHA256', Blob.valueOf(message), Blob.valueOf(privatekey), EncodingUtil.convertFromHex(hmacvalue));

Mehr Webhooks?​

Wenn Sie mehr Webhooks für verschiedene Ereignisse oder mehr Daten darin benötigen, kontaktieren Sie uns und bringen Sie Ihre Anfrage in die Entwicklungspipeline ein.

Schema-Referenz​

Es gibt zwei mögliche Schemata, eines für das Objekt „document“ und ein weiteres für das Objekt „recipient“. Beide Schemata haben Top-Level-Schlüssel „object“ und „event“. Prüfen Sie das Attribut „object“, um das Schema zu bestimmen, mit dem Sie es zu tun haben. Oder verwenden Sie einen Webhook-Filter, um nur Dokument- oder nur Empfängerobjekte zurückzugeben.

Bitte beachten Sie, dass jederzeit neue Attribute zum Schema hinzugefügt werden können (aber nicht entfernt).

1. JSON-Schema für das Objekt „document“​

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "document"
},
"created": {
"type": "integer",
"description": "unix timestamp"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(created|rejected|finalPdfCreated)$"
},
"data": {
"type": "object",
"properties": {
"tag1": {
"type": "string"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer"
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60)$"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string",
"pattern": "^(signer|approver|witness)$"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
}
},
"required": [
"uuid",
"email",
"order",
"status",
"lastname",
"roleText",
"firstname",
"statusText",
"resourceUri",
"rejectReason"
]
}
]
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"statusText": {
"type": "string",
"pattern": "^(available|fields complete|completed|removed|rejected|unknown)$"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"tag2": {
"type": "string"
},
"group": {
"type": "string"
},
"status": {
"type": "integer",
"pattern": "^(10|20|30|40|50)$"
}
},
"required": [
"tag1",
"recipients",
"groupResourceUri",
"statusText",
"name",
"tag",
"resourceUri",
"uuid",
"tag2",
"group",
"status"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}

2. JSON-Schema für das Objekt „recipient“​

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "recipient"
},
"created": {
"type": "integer",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(emailOpened|bounced|visiting|rejected|completed|autoReminderEmail|emailNotification)$"
},
"data": {
"type": "object",
"properties": {
"tag": {
"type": "string"
},
"tag1": {
"type": "string"
},
"tag2": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"group": {
"type": "string",
"format": "uuid"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer",
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60|70)$"
},
"document": {
"type": "string"
},
"documentName": {
"type": "string"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"emailBounce": {
"type": "integer"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"emailBounceMessage": {
"type": "string"
},
"documentResourceUri": {
"type": "string",
"format": "uri-reference"
}
},
"required": [
"tag",
"tag1",
"tag2",
"uuid",
"email",
"group",
"order",
"status",
"document",
"documentName",
"lastname",
"roleText",
"firstname",
"statusText",
"emailBounce",
"resourceUri",
"rejectReason",
"groupResourceUri",
"emailBounceMessage",
"documentResourceUri"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}