Überblick über Webhooks für Acrobat Sign

Überblick

Ein Webhook ist eine selbstdefinierte HTTPS-Anforderung, die ausgelöst wird, wenn ein abonniertes Ereignis auf der Quell-Website (in diesem Fall Adobe Acrobat Sign) auftritt.

Im Prinzip ist ein Webhook also nichts anderes als ein REST-Service, der Daten oder einen Datenstrom akzeptiert.

Webhooks sind für die Dienst-zu-Dienst-Kommunikation in einem PUSH-Modell konzipiert.

Wenn ein abonniertes Ereignis ausgelöst wird, erstellt Acrobat Sign eine HTTPS-POST-Anforderung mit einem JSON-Text und stellt diese für die angegebene URL bereit.

Vergewissere dich vor der Konfiguration von Webhooks, dass dein Netzwerk die für die Funktionalität erforderlichen IP-Bereiche akzeptiert.

Webhooks bieten im Vergleich zur vorherigen Callback-Methode mehrere Vorteile, darunter:

• Admins können ihre Webhooks aktivieren, ohne dass sie den Acrobat Sign-Support zur Auflistung der Rückruf-URL einbeziehen müssen.
• Webhooks sind in Bezug auf Datenaktualität, effiziente Kommunikation und Sicherheit leistungsfähiger. Keine Auswahl erforderlich
• Webhooks lassen unterschiedliche Umfangsbereiche (Konto/Gruppe/Benutzer/Ressource) zu. 
• Webhooks sind eine modernere API-Lösung, die eine einfachere Konfiguration moderner Anwendungen ermöglicht.
• Pro Geltungsbereich (Konto/Gruppe/Benutzer/Ressource) können mehrere Webhooks konfiguriert werden, wohingegen Callbacks eindeutig sein mussten.
• Webhooks ermöglichen die Auswahl der zurückzugebenden Daten, wohingegen Callbacks eine „Alles oder nichts“-Lösung sind.
• Es kann konfiguriert werden, welche Metadaten (einfach oder detailliert) mit einem Webhook übertragen werden
• Webhooks sind wesentlich einfacher zu erstellen, zu bearbeiten oder nach Bedarf zu deaktivieren, da die Benutzeroberfläche vollständig der Kontrolle der Administrator*innen unterliegt.

Voraussetzungen

Du musst sicherstellen, dass dein Netzwerksicherheitssystem die IP-Bereiche für Webhooks akzeptiert, damit der Dienst funktioniert. 

Bei dem älteren Rückruf-URL-Dienst in REST v5 werden dieselben IP-Bereiche verwendet wie beim Webhook-Dienst.

Und so funktioniert's

Administratoren benötigen zunächst einen Webhook-Dienst, der bereit ist, eingehende Push-Nachrichten von Acrobat Sign zu akzeptierten. Hierfür gibt es viele Optionen. Solange der Dienst POST- und GET-Anforderungen akzeptieren kann, ist der Webhook erfolgreich.

Sobald der Dienst eingerichtet ist, kann ein Acrobat Sign-Administrator einen neuen Webhook über die Webhook-Benutzeroberfläche im Kontomenü der Acrobat Sign-Website erstellen.

Admins können den Webhook so konfigurieren, dass er für Ereignisse im Zusammenhang mit Vereinbarungen, Webformularen (Widget) oder dem Massenversand (MegaSign) ausgelöst wird. Die Bibliotheksvorlagen-(Bibliotheksdokument-)ressource kann auch über die API konfiguriert werden.

Der Geltungsbereich des Webhook kann das gesamte Konto oder einzelne Gruppen über die Admin-Oberfläche umfassen. Die API ermöglicht durch die Auswahl der Geltungsbereiche USER oder RESOURCE eine größere Granularität.

Die Art der Daten, die an die URL übertragen werden, ist konfigurierbar und kann z. B. Vereinbarungsinformationen, Teilnahmeinformationen, Dokumentinformationen usw. umfassen.

Nachdem der Webhook konfiguriert und gespeichert wurde, sendet Acrobat Sign jedes Mal ein neues JSON-Objekt an die definierte URL, wenn das abonnierte Ereignis ausgelöst wird. Eine laufende Bearbeitung des Webhooks ist nicht erforderlich, es sei denn, du möchtest die Kriterien für die Ereignisauslösung oder die JSON-Payload ändern.

Überprüfung des Intents der Webhook-URL

Bevor ein Webhook erfolgreich registriert wird, überprüft Acrobat Sign, ob die Webhook-URL, die in der Registrierungsanforderung angegeben ist, Benachrichtigungen erhalten möchte oder nicht. Wenn Acrobat Sign eine neue Webhook-Registrierungsanforderung erhält, wird zunächst eine Überprüfungsanforderung an die Webhook-URL gesendet. Bei dieser Überprüfungsanforderung handelt es sich um eine HTTPS-GET-Anforderung, die an die Webhook-URL gesendet wird. Diese Anforderung hat den benutzerdefinierten HTTP-Header „X-AdobeSign-ClientId“. Der Wert in diesem Header ist auf die Client-ID (Anwendungs-ID) der API-Anwendung festgelegt, die die Erstellung/Registrierung des Webhooks anfordert. Um einen Webhook erfolgreich zu registrieren, muss die Webhook-URL mit einem 2XX-Antwortcode auf diese Überprüfungsanforderung reagieren. DARÜBER HINAUS MUSS die Webhook-URL zusätzlich denselben Client-ID-Wert auf eine der beiden folgenden Weisen zurücksenden:

• Entweder mit „X-AdobeSign-Certified“ in der Kopfzeile der Antwort. Dies ist die gleiche Kopfzeile, die in der Anfrage übergeben wurde und in der Antwort als Echo ausgegeben wird.
• Oder im JSON-Antworttext, wobei der Schlüssel von xAdobeSignClientId und dessen Wert dieselbe Client-ID sind, die in der Anforderung gesendet wurde.

Der Webhook wird nur bei einer erfolgreichen Antwort (2XX-Antwortcode) und Validierung der Client-ID in Kopfzeile oder Antworttext erfolgreich registriert. Ziel dieser Überprüfungsanforderung ist, anzuzeigen, dass deine Webhook-URL tatsächlich Benachrichtigungen unter dieser URL erhalten möchte. Wenn du versehentlich die falsche URL eingegeben hast, reagiert die URL nicht korrekt auf die Überprüfung der Intent-Anforderung und Acrobat Sign sendet keine Benachrichtigungen an diese URL. Darüber hinaus kann die Webhook-URL auch validieren, dass sie Benachrichtigungen nur über die Webhooks erhält, die von einer bestimmten Anwendung registriert wurden. Dies kann durch Validierung der Client-ID der Anwendung erfolgen, die in der X-AdobeSign-ClientId-Kopfzeile übergeben wurde. Wenn die Webhook-URL diese Client-ID nicht erkennt, DARF SIE NICHT mit dem Erfolgsantwortcode antworten und Acrobat Sign sorgt dafür, dass die URL nicht als Webhook registriert wird.

Die Verifizierung des Webhook-URL-Aufrufs erfolgt in den folgenden Szenarien:

• Webhook-Registrierung: Wenn diese Überprüfung des Webhook-URL-Aufrufs fehlschlägt, wird der Webhook nicht erstellt.
• Webhook-Aktualisierung: INAKTIV in AKTIV: Wenn diese Überprüfung des Webhook-URL-Aufrufs fehlschlägt, wird der Webhook-Status nicht in AKTIV geändert.

So reagierst du auf eine Webhook-Benachrichtigung

Acrobat Sign führt eine implizite Überprüfung des Intents in jeder Webhook-Benachrichtigungsanforderung durch, die an die Webhook-URL gesendet wird. Daher enthält jede Webhook-HTTPS-Benachrichtigungsanforderung auch den benutzerdefinierten HTTP-Header mit der Bezeichnung „X-AdobeSign-ClientId“. Der Wert dieses Headers ist die Client-ID (Anwendungs-ID) der Anwendung, die den Webhook erstellt hat. Die Webhook-Benachrichtigung gilt nur dann als erfolgreich zugestellt, wenn, und nur wenn, eine erfolgreiche Antwort (2XX-Antwortcode) zurückgegeben wird und die Client-ID entweder in der HTTP-Kopfzeile (X-AdobeSign-ClientId) oder in einem JSON-Antworttext mit dem Schlüssel „xAdobeSignClientId“ und dem Wert derselben Client-ID gesendet wird. Andernfalls wird erneut versucht, die Benachrichtigung an die Webhook-URL zu senden, bis die Wiederholungsversuche aufgebraucht sind.

Aktivierung oder Deaktivierung

Der Zugriff auf die Webhooks-Funktion ist für Konten auf Unternehmensebene standardmäßig aktiviert.

Admins auf Gruppenebene können die Webhooks steuern/erstellen, die nur innerhalb ihrer jeweiligen Gruppen arbeiten.

Der Zugriff auf die Seite Webhooks ist in der linken Leiste des Admin-Menüs zu finden.

Ratenbegrenzung für gleichzeitig ausgeführte Anforderungen

Benachrichtigungsereignisse sowie die Erstellung von Webhooks (und Callbacks) sind auf die Anzahl der gleichzeitigen Benachrichtigungen begrenzt, die vom Acrobat Sign-System aktiv an die Kundschaft gesendet werden. Dieses Limit gilt für das Konto, sodass alle Gruppen innerhalb des Kontos eingeschlossen sind.
Durch diese Art der Ratenbegrenzung wird verhindert, dass ein schlecht konzipiertes Konto eine unverhältnismäßige Menge an Serverressourcen verbraucht, was sich negativ auf alle anderen Kundinnen und Kunden in dieser Serverumgebung auswirkt.

Die Anzahl der gleichzeitigen Ereignisse pro Konto wurde berechnet, um zu gewährleisten, dass Konten mit korrekt konfigurierten Webhooks ihre Benachrichtigungen in kürzester Zeit erhalten. Dadurch sollte nur in seltenen Fällen eine Situation eintreten, bei der Benachrichtigungen aufgrund zu vieler Anfragen verzögert werden. Die aktuellen Schwellenwerte lauten:

Bewährte Verfahren

• Abonniere bestimmte, benötigte Ereignisse, um die Anzahl der HTTPS-Anforderungen an den Server zu begrenzen – Je genauer du deine Webhooks gestaltest, desto weniger Volumen musst du durchsuchen.
• Vermeide Dopplungen – Wenn mehr als eine App mit derselben Webhook-URL vorhanden ist und dieselben Nutzerdaten mit jeder der Apps verknüpft sind, wird dasselbe Ereignis mehrmals an deinen Webhook gesendet (einmal pro App). In einigen Fällen kann dein Webhook doppelte Ereignisse empfangen. Deine Webhook-Anwendung sollte darauf vorbereitet sein und Dopplungen nach Ereignis-ID filtern.
• Reagiere immer schnell auf Webhooks – deine App hat nur fünf Sekunden Zeit, um auf Webhook-Anforderungen zu reagieren. Bei der Verifizierungsanforderung ist dies selten ein Problem, da deine App keine echte Arbeit leisten muss, um zu reagieren. Bei Benachrichtigungsanfragen tut deine App jedoch in der Regel etwas, das Zeit in Anspruch nimmt, um auf die Anfrage zu reagieren. Es wird empfohlen, an einem separaten Thread oder asynchron mit einer Warteschlange zu arbeiten, um sicherzustellen, dass du innerhalb von fünf Sekunden reagieren kannst.
• Gleichzeitigkeit verwalten – Wenn ein Benutzer mehrere Änderungen in schneller Folge vornimmt, erhält deine App wahrscheinlich mehrere Benachrichtigungen für denselben Benutzer ungefähr zur gleichen Zeit. Wenn du Gleichzeitigkeit nicht sorgfältig verwaltest, verarbeitet deine App dieselben Änderungen für denselben Benutzer unter Umständen mehr als einmal. Um die Vorteile von Acrobat Sign-Webhooks zu nutzen, musst du eine klare Vorstellung davon haben, wie die Informationen verwendet werden sollen. Denke daran, Fragen wie die folgenden zu stellen:
  • Welche Daten sollen in der Nutzlast zurückgegeben werden? 
  • Wer wird auf diese Informationen zugreifen? 
  • Welche Entscheidungen oder Berichte werden generiert?
• Empfehlungen für den Empfang eines signierten Dokuments: Bei der Entscheidung, wie eine signierte PDF-Datei von Acrobat Sign in deinem Dokumentenverwaltungssystem empfangen werden soll, sind mehrere Faktoren zu berücksichtigen.

Auch wenn es durchaus akzeptabel ist, bei der Erstellung eines Webhooks nur die Option Signiertes Vereinbarungsdokument auszuwählen, solltest du die Acrobat Sign-API verwenden, um Dokumente abzurufen, wenn ein auslösendes Ereignis (z. B. Vereinbarungsstatus „Abgeschlossen“) eingeht.

Zu berücksichtigende Punkte...

JSON-Größenbeschränkung

Die JSON-Payload-Größe ist auf 10 MB begrenzt.

Wenn ein Ereignis ein größeres Payload generiert, wird ein Webhook ausgelöst, aber wenn bedingte Parameterattribute in der Anforderung vorhanden sind, werden sie entfernt, um die Größe des Payloads zu reduzieren. 

„ConditionalParametersTrimmed“ wird in der Antwort zurückgegeben, wenn dies geschieht, um Kundinnen und Kunden darüber zu informieren, dass die conditionalParameters-Informationen entfernt wurden.

ConditionalParametersTrimmed ist ein Array-Objekt, das die Informationen über die Keys enthält, die gelöscht wurden.

Die Kürzung wird in der folgenden Reihenfolge durchgeführt:

• includeSignedDocuments
• includeParticipantsInfo
• includeDocumentsInfo
• includeDetailedInfo

Signierte Dokumente werden zuerst abgeschnitten, gefolgt von Teilnehmerdaten., Dokumentinformationen und schließlich ausführliche Information.

Das kann beispielsweise einem Vereinbarungsfertigstellungsereignis, wenn es signiertes Dokument (Base 64 -kodiert) oder für eine Vereinbarung mit mehreren Formularfeldern enthält

Webhook-Benachrichtigungen

Acrobat Sign-Webhooks senden Benachrichtigungen an die sendende Partei der Vereinbarung sowie an alle Webhooks, die innerhalb der Gruppe konfiguriert sind, von der die Vereinbarung gesendet wurde. Im Konto angelegte Webhooks empfangen alle Ereignisse.

Wiederholung des Vorgangs, wenn der Listening-Service heruntergefahren ist

Wenn die Ziel-URL für den Webhook aus irgendeinem Grund nicht funktioniert, fügt Acrobat Sign die JSON-Datei einer Warteschlange hinzu und wiederholt die Übertragung in einem progressiven Zyklus von 72 Stunden.

Nicht zugestellte Ereignisbenachrichtigungen werden in einer Wiederholungswarteschlange gespeichert. Innerhalb der folgenden 72 Stunden wird nach besten Kräften versucht, die Benachrichtigungen in der Reihenfolge zu senden, in der die Ereignisse aufgetreten sind.

Die Strategie beim erneuten Zustellen von Benachrichtigungen ist eine Verdoppelung der Zeit zwischen Versuchen. Es wird mit einem Intervall von einer Minute begonnen bis zu einem Intervall von zwölf Stunden. Daraus ergeben sich 15 Versuche innerhalb von 72 Stunden.

Wenn der Webhook-Empfänger nicht innerhalb von 72 Stunden antwortet und in den letzten sieben Tagen keine erfolgreichen Benachrichtigungszustellungen erfolgt sind, wird der Webhook deaktiviert. Es werden erst Benachrichtigungen zu dieser URL ausgelöst, sobald der Webhook wieder aktiviert wird.

Alle Benachrichtigungen zwischen der Deaktivierung des Webhooks und der anschließenden erneuten Aktivierung gehen verloren.