Configure webhooks

Suchen

Zuletzt aktualisiert am Jan 18, 2023 08:53:47 AM GMT

Ü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.

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.

Hinweis:

Dieses Dokument konzentriert sich hauptsächlich auf die Webhooks-Benutzeroberfläche in der Acrobat Sign-Webanwendung (früher Adobe Sign).

Entwickler*innen, die nach API-Details suchen, finden weitere Informationen hier:

Details REST v6

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, Sie möchten 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 Ihre Webhook-URL tatsächlich Benachrichtigungen unter dieser URL erhalten möchte. Wenn Sie versehentlich die falsche URL eingegeben haben, 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 reagieren Sie 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.

Wie oben erwähnt, sollte der Header „X-AdobeSign-ClientId“, der in jeder Benachrichtigungsanforderung von Sign enthalten ist, in einer Antwort auf eine der beiden folgenden Weisen zurückgegeben werden:

1. HTTP-Header X-AdobeSign-ClientId und Wert der Client-ID

Beispiel-Javascript-Code zum Abrufen der Client-id, Validierung und Rückgabe im Antwortheader
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { //in Antwortheader zurückgeben response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // Standardwert }

PHP-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antwortheader zurückzugeben
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it If( USD clientid == "BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { //in Antwortheader zurückgeben header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // Standardwert } ?>

2. JSON-Antworttext mit dem Schlüssel „xAdobeSignClientId“ und dem Wert derselben Client-ID

Beispieljavascriptcode, um die Client-ID abzurufen, zu validieren und dann im Antworttext zurückzugeben
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { var responseBody = { "xAdobeSignClientId"?: clientid // Rückkehr-Kunden-Identifikation im Haupttext }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; }

Beispieljavascriptcode, um die Client-ID abzurufen, zu validieren und dann im Antworttext zurückzugeben

// Fetch client id

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird

{

var responseBody = {

"xAdobeSignClientId"?: clientid // Rückkehr-Kunden-Identifikation im Haupttext

};

response.headers['Content-Type'] = 'application/json';

response.body = responseBody;

response.status = 200;

}

PHP-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antworttext zurückzugeben
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it If( USD clientid == "BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { //im Antworttext zurückgeben header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // Standardwert } ?>

PHP-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antworttext zurückzugeben

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

If( USD clientid == "BGBQIIE7H253K6") //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird

{

//im Antworttext zurückgeben

header("Content-Type: application/json");

$body = array('xAdobeSignClientId' => $clientid);

echo json_encode($body);

header("HTTP/1.1 200 OK"); // Standardwert

}

Beispiel-JSON Antworttext
{ "xAdobeSignClientId": "BGBQIIE7H253K6" }

Voraussetzungen

Sie müssen:

Ein Microsoft-Konto mit Lizenz zum Erstellen von Azure Functions Applications haben
Ein vorhandene Azure Function Application haben. Sie können eine mithilfe von https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function erstellen
Grundkenntnisse von Javascript haben, damit Sie den Code in jeder beliebigen Sprache Ihrer Wahl verstehen und schreiben können

Schritte zum Erstellen eines Azure Function-Auslösers, der als Acrobat Sign-Webhook fungiert

Um eine JavaScript HTTP-Triggerfunktion zu erstellen:

1. Melden Sie sich über Ihr Microsoft-Konto an. https://portal.azure.com/

2. Öffnen Sie Ihre Azure Function Application, die auf der Registerkarte „Funktions-Apps“ angezeigt wird.

Dadurch wird Ihre Liste von Azure Function Applications geöffnet:

3. Wählen Sie die Anwendung, in der Sie diese neue Funktion erstellen möchten

4. Klicken Sie auf Erstellen (), um eine neue Azure-Funktion zu erstellen.

5. Wählen Sie Webhook + API als das Szenario und JavaScript als Sprache

6. Klicken Sie auf diese Funktion erstellen

Es wird eine neue Funktion erstellt, die eine eingehende API-Anforderung verarbeiten kann.

Logik hinzufügen, um den Acrobat Sign-Webhook zu registrieren

Bevor ein Webhook erfolgreich registriert wird, überprüft Acrobat Sign, ob die Webhook-URL, die in der Registrierungsanforderung angegeben ist, wirklich Benachrichtigungen erhalten möchte oder nicht. Wenn Acrobat Sign eine neue Webhook-Registrierungsanforderung empfängt, wird deshalb zunächst eine Überprüfungsanforderung an die Webhook-URL gestellt. Diese Überprüfungsanforderung ist eine HTTPS-GET-Anforderung, die mit einem benutzerdefinierten HTTP-Header X-AdobeSign-ClientId an die Webhook-URL gesendet wird. Der Wert in diesem Header ist auf die Client-ID der Anwendung festgelegt, die das Erstellen/Registrieren des Webhooks anfordert. Um einen Webhook erfolgreich zu registrieren, muss die Webhook-URL auf diese Überprüfungsanforderung mit einem 2XX-Antwortcode reagieren. ZUSÄTZLICH MUSS die Webhook-URL denselben Client-ID-Wert auf eine der beiden folgenden Weisen zurücksenden:

Es gibt zwei Optionen, die Sie befolgen können:

Option 1: Übergeben Sie die Client-ID mit „X-AdobeSign-ClientId“ als Antwortheader

Übergeben Sie X-AdobeSign-ClientId im Antwortheader. Dies ist der gleiche Titel, der in der Anforderung übergeben wurde, und muss in der Antwort zurückgegeben kopiert werden.

Ersetzen Sie die Index.js-Datei durch Folgendes:

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validieren Sie, dass die eingehende ClientID echt ist

if (clientId === '123XXX456') {

context.res = {

// Status: 200/* Standardwert ist 200 * // jede Antwort im Format 2XX ist akzeptabel

body: "Notification Accepted",

headers : {

'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

}

};

}

else {

context.res = {

status: 400,

body: "Ups!! Illegitimer Aufruf identifiziert"

};

}

context.done();

};

Testen Sie das Verhalten, indem Sie die Anforderung simulieren:

1. Klicken Sie auf die Schaltfläche Test ganz rechts

2. Simulieren Sie die Anforderung

Auch wenn oben keine Antwortheader angezeigt werden, können Sie sie durch die Simulation mit Postman/DHC oder einem anderen Dienst anzeigen lassen.

Option 2: Übergeben Sie die Client-ID im Antworttext mit dem Schlüssel „xAdobeSignClientId“

Im JSON-Antworttext, wobei der Schlüssel vonxAdobeSignClientId und sein Wert dieselbe Client-ID sind, die im Anforderungsheader gesendet wurde.

Ersetzen Sie die Index.js-Datei durch Folgendes:

Inhalt der Datei „index.js“ aktualisieren

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validieren Sie, dass die eingehende ClientID echt ist

if (clientId === '123XXX456') {

context.res = {

// Status: 200/* Standardwert ist 200 * // jede Antwort im Format 2XX ist akzeptabel

'xAdobeSignClientId' : clientId

headers : {

'Content-Type' : 'application/json'

}

};

}

else {

context.res = {

status: 400,

body: "Ups!! Illegitimer Aufruf identifiziert"

};

}

context.done();

};

Testen Sie das Verhalten, indem Sie die Anforderung simulieren

1. Klicken Sie auf die Schaltfläche Test ganz rechts

2. Simulieren Sie die Anforderung

Beachten Sie auch, dass dasselbe Verhalten für clientID erwartet wird, wenn die Webhook-URL POST-Benachrichtigungen empfängt.

Zur Verwendung bereit

Nachdem Sie das Verhalten überprüft haben, funktioniert die Webhook-URL gemäß den Acrobat Sign-Standards. Sie können eine benutzerdefinierte Logik weiter an Ihre Anforderungen anpassen.

Erzielen Sie die Funktion URL

Klicken Sie auf Get Funktion URL

Kopieren Sie die URL und verwenden Sie sie zum Erstellen von Webhooks in Acrobat Sign.

Erstellen der AWS Lambda-Funktion

Um eine AWS Lambda-Funktion zu erstellen, melden Sie sich bei Ihrer AWS Management Console an und wählen Sie den AWS Lambda-Dienst aus der Liste der Dienste aus.

Klicken Sie auf die Option zum Erstellen einer Lambda-Funktion und dann auf Von Grund auf erstellen.
Geben Sie auf der Seite „Funktion konfigurieren“ denFunktionsnamen „lambdaWebhooks“ ein und wählen Sie Node.js 4,3 als Laufzeit aus
Wählen Sie für die Rolle eine vorhandene Rolle aus oder erstellen Sie eine neue Rolle aus den Vorlagen.
- Wenn Sie Neue Rolle aus Vorlage(n) erstellen ausgewählt haben, geben Sie einen Rollennamen ein (z. B. „role-lamda“) und wählen Sie aus der Liste Richtlinienvorlagen die Option Einfache Mikroservices-Berechtigungen aus.
Klicken Sie auf die Schaltfläche Funktion erstellen.

Wählen Sie auf der Seite mit der neuen AWS Lambda-Funktion unter Code-Eingabetyp die Option Code inline bearbeiten aus und behalten Sie „index.handler“ als Handler bei.
Fügen Sie Logik hinzu, um den Acrobat Sign-Webhook zu registrieren.
Bevor ein Webhook erfolgreich registriert wird, überprüft Acrobat Sign, ob die Webhook-URL, die in der Registrierungsanforderung angegeben ist, wirklich Benachrichtigungen erhalten möchte oder nicht. Wenn Acrobat Sign eine neue Webhook-Registrierungsanforderung empfängt, wird deshalb zunächst eine Überprüfungsanforderung an die Webhook-URL gestellt. Diese Überprüfungsanforderung ist eine HTTPS-GET-Anforderung, die mit einem benutzerdefinierten HTTP-Header X-AdobeSign-ClientId an die Webhook-URL gesendet wird. Der Wert in diesem Header ist auf die Client-ID der Anwendung festgelegt, die das Erstellen/Registrieren des Webhooks anfordert. Um einen Webhook erfolgreich zu registrieren, muss die Webhook-URL auf diese Überprüfungsanforderung mit einem 2XX-Antwortcode reagieren. ZUSÄTZLICH MUSS die Webhook-URL denselben Client-ID-Wert auf eine der beiden folgenden Weisen zurücksenden: Beachten Sie auch, dass dasselbe Verhalten für clientID erwartet wird, wenn die Webhook-URL POST-Benachrichtigungen empfängt.

Gehen Sie wie in einem der beiden Fälle vor:

Fall 1: Übergeben Sie die Client-ID in „X-AdobeSign-ClientId“ als Antwortheader
- Übergeben Sie X-AdobeSign-ClientId im Antwortheader. Dies ist der gleiche Titel, der in der Anforderung übergeben wurde, und muss in der Antwort zurückgegeben kopiert werden.
  
  Code-Snippet
  Ersetzen Sie in der index.js-Datei das automatisch generierte Code-Snippet durch folgenden Code:

Node.js-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antwortheader zurückzugeben
exports.handler = function index(event, context, callback) { // Client-ID einholen var clientid = event.headers['X-AdobeSign-ClientId']; //Validieren if (clientid ==„BGBQIIE7H253K6“) //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } }

Node.js-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antwortheader zurückzugeben

exports.handler = function index(event, context, callback) {

// Client-ID einholen

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validieren

if (clientid ==„BGBQIIE7H253K6“) //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird

{

var response = {

statusCode: 200,

headers: {

"X-AdobeSign-ClientId": clientid

}

};

callback(null,response);

}

else {

callback("Oops!! illegitimate call");

}

Fall 2: Übergeben Sie die Client-ID im Antworttext mit dem Schlüssel xAdobeSignClientId

Im JSON-Antworttext, wobei der Schlüssel vonxAdobeSignClientId und sein Wert dieselbe Client-ID sind, die im Anforderungsheader gesendet wurde.

Code Snippet

Ersetzen Sie die Index.js-Datei durch Folgendes :

Node.js-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antwortheader zurückzugeben
exports.handler = function index(event, context, callback) { // Client-ID einholen var clientid = event.headers['X-AdobeSign-ClientId']; //Validieren if (clientid ==„BGBQIIE7H253K6“) //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird { var responseBody = { xAdobeSignClientId : clientid }; var response = { statusCode: 200, body: JSON.stringify(responseBody) }; callback(null,response); } else { callback("Opps!! illegitimate call"); } }

Node.js-Beispielcode, um die Client-ID abzurufen, zu validieren und dann im Antwortheader zurückzugeben

exports.handler = function index(event, context, callback) {

// Client-ID einholen

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validieren

if (clientid ==„BGBQIIE7H253K6“) //Ersetzen Sie „BGBQIIE7H253K6“ durch die Client-ID der Anwendung, mit der der Webhook erstellt wird

{

var responseBody = {

xAdobeSignClientId : clientid

};

var response = {

statusCode: 200,

body: JSON.stringify(responseBody)

};

callback(null,response);

}

else {

callback("Opps!! illegitimate call");

}

Speichern Sie die Funktion. Die Lambda-Funktion wird erstellt und wir können sie nun bald in einem Echtzeit-Webhook verwenden.

Konfigurieren des AWS API Gateway

Um Lambda über eine HTTP-Methode öffentlich zugänglich zu machen, müssen wir das AWS API Gateway mit unserer (oben erstellten) Funktion als Backend für die API konfigurieren.

Wählen Sie in der AWS Management Console das API Gateway aus den AWS-Diensten aus und klicken Sie auf die Schaltfläche API erstellen.

Wählen Sie auf der Seite Neue API erstellen die Option Neue API aus und geben Sie Webhooks als API-Name ein.
Klicken Sie auf die Schaltfläche API erstellen.
Wählen Sie die Dropdown-Liste Aktionen und dann die Option Ressource erstellen aus.
Aktivieren Sie die OptionAls Proxyressource konfigurieren und geben Sie validate als Ressourcenname und {proxy+} in den Ressourcenpfad ein.
Lassen Sie die Option API Gateway CORS aktivieren deaktiviert und klicken Sie auf die Schaltfläche Ressource erstellen.
Lassen Sie die Option Lambda-Funktions-Proxy als Integrationstyp ausgewählt und wählen Sie in der Dropdown-Liste Lambda-Region die Region aus, in der Sie die Lambda-Funktion erstellt haben (dies ist wahrscheinlich dieselbe Region, in der Sie das API Gateway erstellen).
Geben Sie validate als Lambda-Funktion ein und klicken Sie auf die Schaltfläche Speichern.
Klicken Sie im Popup-Fenster Berechtigung zu Lambda-Funktion hinzufügen auf OK.

Wenn alle oben genannten Schritte erfolgreich ausgeführt werden, wird ungefähr der folgende Bildschirm angezeigt:

Bereitstellen der API

Der nächste Schritt besteht darin, diese API so bereitzustellen, dass sie verwendet werden kann.

Wählen Sie in der Dropdown-Liste Aktionen die Option API bereitstellen aus.
Wählen Sie unter Bereitstellungsphase die Option [Neue Phase] aus und geben Sie unter Phasenname Produktion oder einen beliebigen anderen Wert zur Identifizierung der betreffenden Phase ein.
Klicken Sie auf die Schaltfläche Bereitstellen.

Die API ist jetzt einsatzbereit und Sie finden die Invoke-URL im blauen Feld, wie unten dargestellt:

Notieren Sie sich diese URL, da Sie sie als URL für den Echtzeit-Webhook eingeben müssen.

Zur Verwendung bereit

Fertig. Verwenden Sie diese URL oben mit dem Anhang „/{nodeJSfunctionName}“ als Webhook-URL in der POST /webhooks API-Anforderung. Nachdem Sie das Verhalten überprüft haben, funktioniert die Webhook-URL gemäß den
Acrobat Sign-Standards. Sie können die benutzerdefinierte Logik Ihren Anforderungen entsprechend weiter aktualisieren/hinzufügen.

Konfigurationsoptionen

Die Konfiguration des Webhook erfordert fünf Elemente definiert werden:

Name – wir empfehlen einen intuitiven Namen, den andere Administrator*innen sofort verstehen können.
Umfang: Welches Ausmaß eines Netzwerk wird von dem Webhook abgedeckt? Konto und Gruppe sind auf der Oberfläche verfügbar.
- Die API unterstützt die Bereiche „Konto“, „Gruppe“, „Benutzer“ und „Ressourcen“.
- Pro Webhook kann nur ein Umfang definiert werden.
URL: die Ziel-URL, an die Acrobat Sign die JSON-Nutzlast überträgt.
Ereignisse: der Auslöser, der Acrobat Sign dazu veranlasst, die JSON-Datei zu erstellen und an die URL zu übertragen.
- Jedes Ereignis erstellt eine andere Nutzlast, die für das Auslöserereignis relevant ist.
- In einem Webhook können mehrere Ereignisse enthalten sein.
Benachrichtigungsparameter: Mit den Benachrichtigungsparametern werden die Abschnitte der JSON-Ereignis-Nutzlast identifiziert, sodass Sie nur die Abschnitte des Ereignisses auswählen können, die für den betreffenden Webhook relevant sind (damit reduzieren Sie nicht notwendige Daten, die an Ihre URL gesendet werden).

Wenn der Webhook vollständig definiert ist, klicken Sie auf Speichern, und der neue Webhook reagiert sofort auf auslösende Ereignisse.

Hinweis:

Konfigurieren Sie die Webhook-URL so, dass sie auf die Webhook-Überprüfungs- und Webhook-Benachrichtigungsanforderungen gemäß dem oben erläuterten Überprüfungsprotokoll reagiert. Die Client-ID (Anwendungs-ID), die an über die Acrobat Sign-Webanwendung erstellte Webhooks gesendet wird, lautet „UB7E5BXCXY“.

Geltungsbereiche

Konto: Alle abonnierten Ereignisse, die im Konto auftreten, lösen den Push-Vorgang aus.
- Konto-Admins sind berechtigt, alle für das Konto definierten Webhooks und alle Gruppen innerhalb dieses Kontos anzuzeigen.
Gruppe: Alle abonnierten Ereignisse, die in der Gruppe auftreten, lösen den Push-Vorgang aus. HINWEIS: Webhooks im Geltungsbereich der Gruppe existieren nur für diese eine Gruppe.
- Gruppen-Admins sehen nur die Webhooks für ihre Gruppe. Sie können Webhooks auf Kontoebene oder Webhooks, die an andere Gruppen gebunden sind, nicht anzeigen.
- Bei Konten, bei denen die Option Nutzende in mehreren Gruppen aktiviert ist, wird eine Option angezeigt, mit der die Gruppe festgelegt werden kann, auf die der Geltungsbereich angewendet werden soll.
Benutzerkonto: Alle abonnierten Ereignisse für ein Benutzerkonto lösen den Push-Vorgang aus. Webhooks auf Benutzerebene können nur über die API erstellt werden.
Webhook auf Ressourcenebene: Werden für eine spezifische Ressource erstellt. Die Ereignisse, die für diese Ressource spezifisch sind, werden an die Webhook-URL weitergeleitet. Webhooks auf Ressourcenebene können nur über die API erstellt werden.

URL

Eine Webhook-URL ist ein Server, der auf eingehende HTTPS-POST-Benachrichtigungsmeldungen wartet, die ausgelöst werden, wenn Ereignisse auftreten.

Sie benötigen diese URL, damit Ihr Webhook Ereignisse abonnieren kann.

Der Client muss eine HTTPS-URL enthalten, an die Acrobat Sign POST-Anforderungen senden kann. Diese URL muss im öffentlichen Internet verfügbar sein.
- 127.0.0.1- und localhost-URIs funktionieren beispielsweise nicht..
- Der URL-Endpunkt muss den Port 443 oder 8443 überwachen (wird von der Kundschaft beim Definieren der Callback-URL festgelegt).
Stellen Sie sicher, dass der Webhook POST-Anforderungen für eingehende Ereignisbenachrichtigungen und GET-Anforderungen für die Überprüfungsanforderung unterstützt.
Die URL sollte nicht von einer Firewall blockiert werden.

Ereignisse

Im Folgenden finden Sie die Ereignisse, die eine Push-Übertragung an die Webhook-URL auslösen können, nach Objekten zusammengefasst und in derselben Reihenfolge aufgeführt wie in der Bedienoberfläche.

Der Wert auf der linken Seite ist der Wert, der in der Acrobat Sign-Bedienoberfläche angezeigt wird. Der Wert auf der rechten Seite ist der Webhook-Name in der API.

Ausführliche Informationen zu Webhooks und ihren Nutzlasten finden Sie im Acrobat Sign-Entwicklungshandbuch.

Vereinbarungen:

UI-Element	Webhook-Name
Vereinbarung – alle Ereignisse	AGREEMENT_ALL
Vereinbarung erstellt	AGREEMENT_CREATED
Vereinbarung gesendet	AGREEMENT_ACTION_REQUESTED
Vereinbarungsteilnehmende abgeschlossen	AGREEMENT_ACTION_COMPLETED
Vereinbarungs-Workflow abgeschlossen	AGREEMENT_WORKFLOW_COMPLETED
Vereinbarung abgelaufen	AGREEMENT_EXPIRED
Vereinbarung gelöscht	AGREEMENT_DOCUMENTS_DELETED
Vereinbarung storniert	AGREEMENT_RECALLED
Vereinbarung abgelehnt	AGREEMENT_REJECTED
Vereinbarung freigegeben	AGREEMENT_SHARED
Vereinbarung delegiert	AGREEMENT_ACTION_DELEGATED
Vereinbarungsteilnehmende ersetzt	AGREEMENT_ACTION_REPLACED_SIGNER
Vereinbarung geändert	AGREEMENT_MODIFIED
Vereinbarungsänderung bestätigt	AGREEMENT_USER_ACK_AGREEMENT_MODIFIED
Vereinbarungs-E-Mail angezeigt	AGREEMENT_EMAIL_VIEWED
Vereinbarungs-E-Mail nicht zustellbar	AGREEMENT_EMAIL_BOUNCED
Fehler bei Vereinbarungserstellung	AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
Vereinbarung nach Offlineereignis synchronisiert	AGREEMENT_OFFLINE_SYNC
Vereinbarung von sendender Partei hochgeladen	AGREEMENT_UPLOADED_BY_SENDER
Vereinbarung archiviert	AGREEMENT_VAULTED
Soziale Identität der an der Vereinbarung teilnehmenden Partei authentifiziert	AGREEMENT_WEB_IDENTITY_AUTHENTICATED
Vereinbarungsteilnehmende per KBA authentifiziert	AGREEMENT_KBA_AUTHENTICATED
Vereinbarungsablauf aktualisiert	AGREEMENT_EXPIRATION_UPDATED
Vereinbarungserinnerung gesendet	AGREEMENT_REMINDER_SENT
Der Name der die Vereinbarung unterzeichnenden Partei wurde von der unterzeichnenden Partei geändert	AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER
Vereinbarungserinnerung gestartet	AGREEMENT_REMINDER_INITIATED

Nur über die API verfügbare Vereinbarungs-Webhooks
UI-Element	Webhook-Name
N/A	AGREEMENT_READY_TO_NOTARIZE
N/A	AGREEMENT_READY_TO_VAULT

Massenversand:

UI-Element	Webhook-Name
Massenversand – alle Ereignisse	MEGASIGN_ALL
Massenversand – erstellt	MEGASIGN_CREATED
Massenversand – freigegeben	MEGASIGN_SHARED
Massenversand – zurückgerufen	MEGASIGN_RECALLED
Massenerinnerung gesendet	MEGASIGN_REMINDER_SENT
Massenversand-Erinnerung gestartet	MEGASIGN_REMINDER_INITIATED

Webformulare:

UI-Element	Webhook-Name
Webformular – alle Ereignisse	WIDGET_ALL
Webformular erstellt	WIDGET_CREATED
Webformular aktiviert	WIDGET_ENABLED
Webformular deaktiviert	WIDGET_DISABLED
Webformular geändert	WIDGET_MODIFIED
Webformular freigegeben	WIDGET_SHARED
Erstellen von Webformular fehlgeschlagen	WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

Bibliotheksvorlagen (nur API):

UI-Element	Webhook-Name
N/A	LIBRARY_DOCUMENT_ALL
N/A	LIBRARY_DOCUMENT_CREATED
N/A	LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
N/A	LIBRARY_DOCUMENT_MODIFIED

Benachrichtigungsparameter

Mitteilungs-Parameter ermöglichen es Ihnen, die JSON-Nutzlast nur bestimmten Elementen des Ereignisses anzupassen.

Bei einem Vereinbarungsteilnehmende ersetzt-Ereignis könnten Sie zum Beispiel nur die Vereinbarungsinformationen und die Teilnahmeinformationen erhalten wollen, nicht die Dokumentinformationen, wodurch sich das Gesamtvolumen der an Ihre Webhook-URL gesendeten JSON-Daten verringert.

Vereinbarung
- Vereinbarungsinformationen: detaillierte Vereinbarungsinformationen basierend auf dem Status der Vereinbarung zum Zeitpunkt des auslösenden Ereignisses.
- Vereinbarungs-Dokumenten-Informationen: enthält alle Dokumentinformationen, die aufgrund des Ereignisses generiert werden.
- Informationen zur Vereinbarungsteilnahme: Enthält alle Informationen zu den Teilnehmenden als Ergebnis des Ereignisses.
- Bei der Vereinbarung unterzeichnetes Dokument: Stellt die signierte PDF-Datei zur Verfügung.
  - Gilt für die Ereignisse Vereinbarungsworkflow abgeschlossen und Vereinbarung alle.
Massenversand
- Massenversand – Informationen: detaillierte Informationen über das Massenversand-Objekt, das das Ereignis ausgelöst hat.
Webformular
- Widget-Informationen: detaillierte Informationen über das Webformular, das das Ereignis ausgelöst hat..
- Informationen zum Widget-Dokument: die Dokumentinformationen, die mit dem Webformular verknüpft sind.
- Informationen zur Widget-Teilnahme: Informationen zu den im Webformular definierten Teilnehmenden.

Zwei-Wege-SSL-Authentifizierung

Zwei-Wege-SSL, oft auch als clientseitiges SSL oder „Mutual TLS“ bezeichnet, ist ein SSL-Modus, bei dem sowohl der Server als auch der Client (Webbrowser) Zertifikate zur Identifizierung vorlegen.

Kontoadministrator*innen können ein clientseitiges Zertifikat auf der Seite Sicherheitseinstellungen konfigurieren.

Acrobat Sign überprüft die SSL-Zertifikate bei der Bereitstellung von Payloads an die Webhook-URL. Webhooks, die nicht erfolgreich auf SSL-Zertifikate geprüft werden, stellen die JSON-Nutzlast nicht erfolgreich zu.

Verwenden Sie Zwei-Wege-SSL zur Authentifizierung des Clients (Acrobat Sign) und des Listening-Service, um sicherzustellen, dass nur Acrobat Sign Ihre Webhook-URL abrufen kann.

Wenn der Webhook von einer Partneranwendung erstellt wurde, verwendet der Webhook ein Clientzertifikat (falls verfügbar) aus dem Konto der Partneranwendung, um sich beim Senden von Webhook-Benachrichtigungen zu identifizieren.

Zu den Steuerelementen der Bedienoberfläche navigieren, um ein Clientzertifikat hochzuladen

Im Folgenden finden Sie die häufigsten Fragen sowohl zur Überprüfung des Webservers als auch zur Überprüfung der Clientzertifizierung.

Webserverüberprüfung

Während der Registrierung eines Webhooks überprüft Acrobat Sign die URL des Webhook-Servers.

Sie können den Webhook nicht registrieren, wenn die Verbindung mit der Webhook-Rückruf-URL von Acrobat Sign nicht abgeschlossen werden kann.

Nein.

Für die Webhook-Callback-URL kann nur HTTPS auf Port 443 oder 8443 verwendet werden.

Acrobat Sign blockiert ausgehenden HTTPS-Traffic für alle anderen Ports
.

Eine gute Möglichkeit, das Serverzertifikat zu überprüfen, ist die Verwendung des DigiCert® SSL-Installationsdiagnosetools.

Geben Sie nur den Hostnamen ein, z. B.: www.digicert.com.

Häufige Probleme:

Problem: Es wird eine nicht vertrauenswürdige Zertifizierungsstelle oder ein selbstsigniertes Zertifikat verwendet.

Korrektur: Verwenden Sie ein von einer öffentlichen Zertifizierungsstelle ausgestelltes SSL-Zertifikat für den Webhook-Rückrufserver.

Nicht vertrauenswürdige Zertifizierungsstelle

Problem: Der Server sendet das Intermediate-Zertifikat nicht.

Korrektur: Installieren Sie die Intermediate-Zertifikate auf dem Webhook-Rückrufserver.

Weitere Informationen finden Sie unter https://www.digicert.com/kb/ssl-certificate-installation.htm.

Überprüfung des Clientzertifikats

Um Zwei-Wege-SSL für einen Webhook einzurichten, müssen Admins eine P12- (oder PFX-)Datei hochladen, die den privaten Schlüssel enthält. Die Datei wird sicher im Nutzungskonto gespeichert und die Admins können sie jederzeit wieder entfernen.

In einem bidirektionalen Webhook-Setup ist Acrobat Sign der Anrufer/Client und benötigt den privaten Schlüssel, um nachzuweisen, dass der Anruf von Acrobat Sign im Namen des Nutzungskontos erfolgt.

Stellen Sie sicher, dass Zwei-Wege-SSL aktiviert ist.

Zwei-Wege-SSL muss auf dem Webhook-Rückrufserver aktiviert sein.

Stellen Sie mit einem beliebigen Webbrowser eine Verbindung zur Webhook-Rückruf-URL her. Die folgende Meldung sollte angezeigt werden:
```
400 Bad Request
No required SSL certificate sent
```
Dies bedeutet, dass der Server vom Client erwartet, dass dieser Clientzertifikate sendet (d. h. Zwei-Wege-SSL ist für den Server aktiviert).

Wenn die obige Meldung nicht angezeigt wird, ist Zwei-Wege-SSL nicht aktiviert.

Hinweis:

Sie können mit Postman eine POST-Anfrage an die Webhook-Rückruf-URL durchführen. Sie sollten ein ähnliches Ergebnis erhalten.

Überprüfen Sie das Clientzertifikat lokal.

Die Clientanmeldedaten können entweder ein selbstsigniertes Zertifikat oder ein von einer Zertifizierungsstelle ausgestelltes Zertifikat sein. Sie müssen jedoch mindestens den folgenden X.509 v3-Erweiterungen entsprechen:

X.509 v3-Erweiterung	Wert
ExtendedKeyUsage	clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage	digitalSignature

Das Clientzertifikat muss eine PKCS12-Datei mit der Erweiterung .p12 oder .pfx sein und Folgendes enthalten: das Clientzertifikat (damit der Server die Identität des Clients überprüfen kann) und den privaten Schlüssel des Clients (damit der Client Nachrichten digital signieren kann, die der Server während des SSL-Handshakes überprüfen kann).

Verwenden Sie den Befehl openssl zum Überprüfen der P12- bzw. PFX-Datei:

openssl pkcs12 -info -in outfile.p12

Die Passphrase für den privaten Schlüssel muss angefordert werden. Die Ausgabe muss sowohl Zertifikate als auch einen verschlüsselten privaten Schlüssel enthalten wie zum Beispiel:

Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
-----BEGIN CERTIFICATE-----
MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
...
JAKQLQ==
-----END CERTIFICATE-----
Bag Attributes: <No Attributes>
subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
-----BEGIN CERTIFICATE-----
MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
...
-----END CERTIFICATE-----
Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
Key Attributes: <No Attributes>
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
...
FHE=
-----END ENCRYPTED PRIVATE KEY-----

Die Zertifikate müssen mindestens das End Entity-Zertifikat und die Intermediate-Zertifikate enthalten. Idealerweise ist auch das Root-CA-Zertifikat enthalten.

Stellen Sie sicher, dass die P12- oder PFX-Datei durch eine Passphrase geschützt ist.

Erstellen Sie ein selbstsigniertes Clientzertifikat (optional).

Clientzertifikate können je nach Bedarf von einer Zertifizierungsstelle ausgestellt oder selbstsigniert sein.

Zum Generieren eines selbstsignierten Clientzertifikats verwenden Sie den folgenden openssl-Befehl:

openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

Vorsicht:

Achten Sie darauf, dass die resultierenden Dateien geheim bleiben, da es sich um Ihre selbstsignierten CA-Zertifikate handelt.
Generieren Sie als Nächstes die P12-Datei des Clients:
1. Generieren Sie einen privaten Schlüssel für den SSL-Client:
  openssl genrsa -out client.key 2048
2. Verwenden Sie den privaten Schlüssel des Clients, um eine Zertifikatanforderung zu generieren:
  openssl req -new -key client.key -out client.req
3. Stellen Sie das Clientzertifikat mithilfe der Zertifikatanforderung und des Zertifizierungsstellenzertifikats/-schlüssels aus:
  openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
4. Konvertieren Sie das Clientzertifikat und den privaten Schlüssel in das Format PKCS#12, sodass sie von Browsern verwendet werden können:
  openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
5. Entfernen Sie den privaten Clientschlüssel, das Clientzertifikat und die Clientanforderungsdateien, da die PKCS12-Datei alles enthält, was Sie benötigen.
  rm client.key client.cer client.req
Überprüfen Sie das Clientzertifikat auf dem Remote-Server.
- Laden Sie mit Postman die Client-PFX-Datei in Einstellungen > Zertifikate hoch.
- Wählen sie Zertifikat hinzufügen aus, um das Clientzertifikat hinzuzufügen.
- Konfigurieren Sie den HTTP-Header für x-adobesign-clientid:
Senden Sie nach der Konfiguration eine POST-Anforderung an die Webhook-Rückruf-URL.

Sie sollten eine 200-Antwort erhalten.
Warum lehnt Acrobat Sign meine PFX-Datei ab, obwohl ich sie mit Postman überprüft habe?

Wenn Sie den oben beschriebenen Vorgang zur Überprüfung der PFX-Datei ausgeführt haben und Acrobat Sign die PFX-Datei immer noch ablehnt, wurde die Datei wahrscheinlich von einem Microsoft-Tool generiert, das eine nicht standardmäßige PKCS12-Datei erstellen kann.

Verwenden Sie in diesem Fall die folgenden openssl-Befehle, um die Zertifikate und den privaten Schlüssel aus der PFX-Datei zu extrahieren und dann eine ordnungsgemäß formatierte PKCS12-Datei zu generieren:
```
// Zertifikate und privaten Schlüssel aus der PFX-Datei extrahieren
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts

// Neue PKCS12-Datei erstellen 
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
```

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.

Webhook aktivieren

Beim Erstellen eines Webhooks hat er zunächst den Status Aktiv.

Auf der Seite Webhooks in Acrobat Sign werden die aktiven Webhooks standardmäßig angezeigt.

Um einen inaktiven Webhook zu aktivieren:

Klicken Sie auf das Symbol Optionen rechts neben der Webhooks-Kopfzeile und wählen Sie Alle Webhooks anzeigen aus

Klicken Sie einmal auf den inaktiven Webhook, um ihn auszuwählen
- Dadurch erscheinen die Optionen für den Webhook direkt unter der Kopfzeile
Klicken Sie Aktivieren

Der aktive Webhook sendet Daten an die Ziel-URL, sobald das nächste Ereignis ausgelöst wird.

Webhook deaktivieren

Um einen Webhook zu deaktivieren, folgen Sie einfach den folgenden Schritten:

Navigieren Sie zur Webhooks-Seite
Wählen Sie den Webhook, den Sie deaktivieren möchten, durch einfaches Klicken aus.
Aktivieren Sie die Option Deaktivieren aus den Menüelementen unter der Kopfzeile
- Nach der Deaktivierung zeigt der Webhook den Status Inaktiv an

Webhook anzeigen oder bearbeiten

Webhooks können jederzeit bearbeitet und gespeichert werden. Beim Speichern einer neuen Konfiguration wird diese Änderung sofort wirksam.

Nur die Ereignisse und Mitteilungs-Parameter können bearbeitet werden.

Wenn der Name, der Umfang oder die URL geändert werden muss, muss ein neuer Webhook erstellt werden.

So bearbeiten Sie die Parameter eines Webhooks:

Navigieren Sie zur Webhooks-Seite
Klicken Sie einmal auf den Webhook, den Sie bearbeiten möchten
Klicken Sie auf die Option anzeigen/bearbeiten unter der Kopfzeile

Nehmen Sie die erforderlichen Änderungen vor und klicken Sie auf Speichern.

Webhook löschen

Ein Webhook kann jederzeit gelöscht werden.

Durch das Löschen eines Webhooks zerstört ihn im System, deshalb gibt es keine Möglichkeit, einen gelöschten Webhook wiederherzustellen.

Webhooks müssen nicht zuerst deaktiviert werden.

Um einen Webhook zu löschen:

Navigieren Sie zu Webhooks
Wählen Sie den Webhook aus, den Sie durch einfaches Klicken löschen möchten.
Klicken Sie auf die Option Löschen unter der Kopfzeile
Es wird eine Warnmeldung angezeigt, um sicherzustellen, dass Sie den Webhook wirklich löschen möchten. Klicken Sie auf OK.

Bewährte Verfahren

Abonnieren Sie bestimmte, benötigte Ereignisse, um die Anzahl der HTTPS-Anforderungen an den Server zu begrenzen – Je genauer Sie Ihre Webhooks gestalten, desto weniger Volumen müssen Sie durchsuchen.
Vermeiden Sie Dopplungen – Wenn Sie mehr als eine App mit derselben Webhook-URL und die selben Nutzerdaten mit jeder der Apps verknüpft sind, wird dasselbe Ereignis mehrmals an Ihren Webhook gesendet (einmal pro App). In einigen Fällen kann Ihr Webhook doppelte Ereignisse empfangen. Ihre Webhook-Anwendung sollte darauf vorbereitet sein und Dopplungen nach Ereignis-ID filtern.
Reagieren Sie immer schnell auf Webhooks – Ihre App hat nur fünf Sekunden Zeit, um auf Webhook-Anforderungen zu reagieren. Bei der Verifizierungsanforderung ist dies selten ein Problem, da Ihre App keine echte Arbeit leisten muss, um zu reagieren. Bei Benachrichtigungsanfragen tut Ihre 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 Sie innerhalb von fünf Sekunden reagieren können.
Gleichzeitigkeit verwalten – Wenn ein Benutzer mehrere Änderungen in schneller Folge vornimmt, erhält Ihre App wahrscheinlich mehrere Benachrichtigungen für denselben Benutzer ungefähr zur gleichen Zeit. Wenn Sie Gleichzeitigkeit nicht sorgfältig verwalten, verarbeitet Ihre App dieselben Änderungen für denselben Benutzer unter Umständen mehr als einmal. Um die Vorteile von Acrobat Sign-Webhooks zu nutzen, müssen Sie eine klare Vorstellung davon haben, wie die Informationen verwendet werden sollen. Denken Sie 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 Ihrem 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, sollten Sie 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 Kund*innen darüber zu informieren, dass die conditionalParameters-Informationen wurden entfernt.

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

Hinweis:

Am 8. November 2022 führte Adobe Acrobat Sign eine verbesserte Version der Webhook-Infrastruktur ein (unter dem Namen dem„Webhooks 2.0“).

Bei allen neuen Konten, die nach der Veröffentlichung vom 8. November 2022 erstellt werden, wird automatisch Webhooks 2.0 aktiviert.
Alle Konten, die vor dem 9. November 2022 erstellt wurden, bleiben bis zum 14. März 2023 im „klassischen“ Webhook-Erlebnis. Danach werden sie automatisch in Webhooks 2.0 migriert.
- Konten mit dem „klassischen“ Webhook-Erlebnis können Webhooks 2.0 nach dem 8. November über das Insider Access-Programm von Adobe in einem Test-, Entwicklungs- oder Sandbox-Konto ausprobieren.
Zum 18. Juli 2023 wird Adobe die „klassische“ Webhook-Infrastruktur auslaufen lassen.

Webhooks 2.0 unterstützt alle Funktionen der klassischen Webhooks mit einer Einschränkung. Wenn ein Webhook für die nutzende Partei, ihre Gruppe oder ihr Konto konfiguriert wurde, haben „klassische“ Webhooks Benachrichtigungen an alle Teilnehmenden einer Vereinbarung gesendet. Bei Webhooks 2.0 gibt es NUR bei der Konfiguration von Webhooks für die sendende Partei, ihre Gruppe oder ihr Konto Benachrichtigungen. Das heißt, Benachrichtigungen werden nicht mehr an alle Teilnehmenden einer Vereinbarung gesendet. Bitte beachten Sie, dass alle zukünftigen Verbesserungen NUR für Webhooks 2.0 bereitgestellt werden.

Kund*innen, die über strenge Netzwerksicherheitsrichtlinien verfügen, müssen neue IP-Adressen gemäß https://helpx.adobe.com/de/sign/system-requirements.html konfigurieren.

Wenn Sie Fragen haben, wenden Sie sich an Ihre*n Success Manager*in oder an das Support-Team.

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.

Der Absender sendet eine Vereinbarung zur Signatur an drei Unterzeichner.

Für das Absenderkonto ist Webhook X auf Kontoebene konfiguriert.
Unterzeichner 1 ist Mitglied desselben Kontos wie der Absender, aber in einer anderen Gruppe. Für diese Gruppe ist Webhook Y konfiguriert.
Unterzeichner 2 ist Mitglied eines anderen Kontos. Für das Konto von Unterzeichner 2 ist Webhook Z auf Kontoebene konfiguriert.
Unterzeichner 3 ist Mitglied desselben Kontos wie der Absender.

Der Absender sendet eine Vereinbarung: Webhook X wird bei den Ereignissen „Vereinbarung erstellt“ und „Vereinbarung gesendet“ ausgelöst, während Webhook Y beim Ereignis „Vereinbarung gesendet“ ausgelöst wird.

Unterzeichner 1 signiert: Webhook X wird bei „Vereinbarungsteilnehmer abgeschlossen“ und „Vereinbarung gesendet“, Webhook Y bei „Vereinbarungsteilnehmer abgeschlossen“ und Webhook Z bei „Vereinbarung gesendet“ ausgelöst.

Unterzeichner 2 signiert: Webhook X wird bei „Vereinbarungsteilnehmer abgeschlossen“ und „Vereinbarung gesendet“ ausgelöst, während Webhook Z bei „Vereinbarungsteilnehmer abgeschlossen“ eine Benachrichtigung sendet.

Unterzeichner 3 signiert: Webhook X wird bei „Vereinbarungsteilnehmer abgeschlossen“ und „Vereinbarungs-Workflow abgeschlossen“ ausgelöst, Webhook Y wird bei „Vereinbarungs-Workflow abgeschlossen“ ausgelöst und Webhook Z wird bei „Vereinbarungs-Workflow abgeschlossen“ ausgelöst.

Sendende Partei: nutzende Partei A | Signierende Partei: nutzende Partei B | Freigabekontakt: nutzende Partei C

Nutzende Partei A und nutzende Partei B befinden sich in verschiedenen Konten

Nutzende Partei A und nutzende Partei C befinden sich in verschiedenen Konten

Anwendungsfall	Benachrichtigung?	Kommentare/Hinweise
Das Konto der nutzenden Partei A verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei A oder der Kontoadministration).	Ja	Ein Webhook auf KONTO-Ebene wird über alle Ereignisse benachrichtigt, die in diesem Konto ausgelöst werden.
Das Konto der nutzenden Partei A verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei A oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A und die Gruppenadministration befinden sich in derselben Gruppe.	Ja	Ein Webhook auf GRUPPEN-Ebene wird über alle Ereignisse benachrichtigt, die in dieser Gruppe ausgelöst werden.
Die nutzende Partei A verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Ja	Als sendende Partei wird der Webhook der nutzenden Partei A auf BENUTZENDEN-Ebene ausgelöst
Die nutzende Partei A hat einen Webhook auf RESSOURCEN-Ebene (für die oben genannte gesendete Vereinbarung).	Ja

Das Konto der nutzenden Partei B verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei B oder der Kontoadministration).	Nein	Der Webhook auf KONTO-Ebene der nutzenden Partei B ist ein Webhook für Unterzeichnende.
Das Konto der nutzenden Partei B verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei B oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei B und die Gruppenadministration befinden sich in derselben Gruppe.	Nein	Der Webhook auf GRUPPEN-Ebene der nutzenden Partei B ist ein Webhook für Unterzeichnende.
Die nutzende Partei B verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Nein	Der Webhook auf BENUTZENDEN-Ebene der nutzenden Partei B ist ein Webhook für Unterzeichnende.

Das Konto der nutzenden Partei C verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei C oder der Kontoadministration).	Nein	Der Webhook auf KONTO-Ebene der nutzenden Partei C wird als Webhook ohne Ursprungseigenschaft betrachtet.
Das Konto der nutzenden Partei C verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei C oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei C und die Gruppenadministration befinden sich in derselben Gruppe.	Nein	Der Webhook auf GRUPPEN-Ebene der nutzenden Partei C wird als Webhook ohne Ursprungseigenschaft betrachtet.
Die nutzende Partei C verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Nein	Der Webhook auf BENUTZENDEN-Ebene der nutzenden Partei C wird als Webhook ohne Ursprungseigenschaft betrachtet.

Sendende Partei: nutzende Partei A | Signierende Partei: nutzende Partei B | Freigabekontakt: nutzende Partei C

Die nutzende Partei A, die nutzende Partei B und die nutzende Partei C befinden sich in demselben Konto

Anwendungsfall	Benachrichtigung?	Hinweise
Das Konto der nutzenden Partei A verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei A oder der Kontoadministration).	Ja	Webhooks auf KONTO-Ebene benachrichtigen über Ereignisse, die vom Konto ausgelöst wurden.
Das Konto der nutzenden Partei A verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei A oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A und die Gruppenadministration befinden sich in derselben Gruppe.	Ja	Webhooks auf GRUPPEN-Ebene benachrichtigen über Ereignisse, die von den Benutzenden in deren Gruppe ausgelöst wurden.
Die nutzende Partei A verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Ja	Der Webhook der nutzenden Partei A als sendenden Partei wird auf BENUTZENDEN-Ebene ausgelöst
Die nutzende Partei A hat einen Webhook auf RESSOURCEN-Ebene (für die oben genannte gesendete Vereinbarung).	Ja

Das Konto der nutzenden Partei B verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei B oder der Kontoadministration).	Ja	Da die nutzende Partei A und die nutzende Partei B sich in demselben Konto befinden, wird ein Webhook auf KONTO-Ebene über alle Ereignisse benachrichtigt, die in diesem Konto ausgelöst werden.
Das Konto der nutzenden Partei B verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei B oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A, die nutzende Partei B und die Gruppenadministration befinden sich in derselben Gruppe.	Ja	Da die nutzende Partei A und die nutzende Partei B sich in demselben Konto befinden, wird ein Webhook auf GRUPPEN-Ebene über alle Ereignisse benachrichtigt, die in dieser Gruppe ausgelöst werden.
Das Konto der nutzenden Partei B verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei B oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A und die nutzende Partei B befinden sich in unterschiedlichen Gruppen.	Nein	Der Webhook auf GRUPPEN-Ebene der nutzenden Partei B ist ein Webhook für Unterzeichnende. Der Webhook der nutzenden Partei A (RESSOURCE/NUTZENDE PARTEI/GRUPPE/KONTO) wird ausgelöst.
Die nutzende Partei B verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Nein	Der Webhook der nutzenden Partei B als empfangenden Partei wird auf BENUTZENDEN-Ebene ausgelöst.

Das Konto der nutzenden Partei C verfügt über einen Webhook auf KONTO-Ebene (erstellt von der nutzenden Partei C oder der Kontoadministration).	Ja	Da die nutzende Partei A und die nutzende Partei C sich in demselben Konto befinden, wird ein Webhook auf KONTO-Ebene über alle Ereignisse benachrichtigt, die in diesem Konto ausgelöst werden.
Das Konto der nutzenden Partei C verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei C oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A, die nutzende Partei C und die Gruppenadministration befinden sich in derselben Gruppe.	Ja	Da die nutzende Partei A und die nutzende Partei C sich in demselben Konto befinden, wird ein Webhook auf GRUPPEN-Ebene über alle Ereignisse benachrichtigt, die in dieser Gruppe ausgelöst werden.
Das Konto der nutzenden Partei C verfügt über einen Webhook auf GRUPPEN-Ebene (erstellt von der nutzenden Partei C oder der Konto-/Gruppenadministration). Annahme: Die nutzende Partei A und die nutzende Partei C befinden sich in unterschiedlichen Gruppen.	Nein	Der Webhook auf GRUPPEN-Ebene der nutzenden Partei C wird als Webhook ohne Ursprungseigenschaft betrachtet. Der Webhook der nutzenden Partei A (RESSOURCE/NUTZENDE PARTEI/GRUPPE/KONTO) wird ausgelöst.
Die nutzende Partei C verfügt über einen Webhook auf BENUTZENDEN-Ebene.	Nein	Der Webhook auf Benutzendenebene der nutzenden Partei C wird als Webhook ohne Ursprungseigenschaft betrachtet.

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.

Bei Ihrem Konto anmelden

Configure webhooks

Überblick

Und so funktioniert's

Überprüfung des Intents der Webhook-URL

So reagieren Sie auf eine Webhook-Benachrichtigung

1. HTTP-Header X-AdobeSign-ClientId und Wert der Client-ID

2. JSON-Antworttext mit dem Schlüssel „xAdobeSignClientId“ und dem Wert derselben Client-ID

Voraussetzungen

Schritte zum Erstellen eines Azure Function-Auslösers, der als Acrobat Sign-Webhook fungiert

Logik hinzufügen, um den Acrobat Sign-Webhook zu registrieren

Option 1: Übergeben Sie die Client-ID mit „X-AdobeSign-ClientId“ als Antwortheader

Option 2: Übergeben Sie die Client-ID im Antworttext mit dem Schlüssel „xAdobeSignClientId“

Zur Verwendung bereit

Erstellen der AWS Lambda-Funktion

Fall 1: Übergeben Sie die Client-ID in „X-AdobeSign-ClientId“ als Antwortheader

Fall 2: Übergeben Sie die Client-ID im Antworttext mit dem Schlüssel xAdobeSignClientId

Konfigurieren des AWS API Gateway

Bereitstellen der API

Zur Verwendung bereit

Konfigurationsoptionen

Geltungsbereiche

URL

Ereignisse

Vereinbarungen:

Massenversand:

Webformulare:

Bibliotheksvorlagen (nur API):

Benachrichtigungsparameter

Zwei-Wege-SSL-Authentifizierung

Webserverüberprüfung

Überprüfung des Clientzertifikats

Aktivierung oder Deaktivierung

Webhook aktivieren

Webhook deaktivieren

Webhook anzeigen oder bearbeiten

Webhook löschen

Bewährte Verfahren

Zu berücksichtigende Punkte...

JSON-Größenbeschränkung

Webhook-Benachrichtigungen

Wiederholung des Vorgangs, wenn der Listening-Service heruntergefahren ist