Configure webhooks

Übersicht

Ein Webhook ist ein benutzerdefinierter HTTPS-Rückruf, der ausgelöst wird, wenn ein bestimmtes Ereignis auf der Quell-Website (in diesem Fall Adobe Acrobat Sign) auftritt.

Ein Webhook ist eigentlich nichts anderes als ein Webservice, der HTTPS-POST-Anforderungen von einer Quelle akzeptiert. Ein Webhook ist also ein REST-Service, der Daten oder einen Datenstrom akzeptiert.

Webhooks sind für? Dienst in servicecommunication? in a? Push-Modell.

Wenn ein Auslöserereignis auftritt, 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:

  • Administratoren können ihre eigenen 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
  • Mehrere Webhooks können pro Geltungsbereich (Konto/Gruppe/Benutzer/Ressource) konfiguriert werden. Callbacks mussten eindeutig sein
  • Webhooks ermöglichen die Auswahl der zurückzugebenden Daten, wohingegen Rückrufe 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:


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.

Administratoren können den Webhook so konfigurieren, dass er für Ereignisse im Zusammenhang mit Vereinbarungen, Webformularen oder dem Massenversand ausgelöst wird.

Der Bereich des webhook kann das gesamte Konto oder die einzelnen Gruppen über die Admin-Oberfläche enthalten. Benutzer- und Ressourcenbereiche sind auch über die API werden

Die Art der Daten, die an die URL übertragen werden, ist konfigurierbar und kann z. B. Vereinbarungsinformationen, Teilnehmerinformationen, das signierte Dokument usw. umfassen.

Nachdem der Webhook konfiguriert und gespeichert wurde, sendet Acrobat Sign jedes Mal ein neues JSON-Objekt an die definierte URL, wenn das Auslöserereignis abgefangen 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, 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. 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 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:

  • Entweder mit „X-AdobeSign-Certified“ in der Kopfzeile der Antwort. Dies ist der gleiche Titel, der in der Anforderung übergeben wurde, und wird in der Antwort kopiert.
  • Oder im JSON-Antworttext, wobei der Schlüssel von xAdobeSignClientId und sein 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 dieses Überprüfungsantrags ist es, anzuzeigen, dass Ihre Webhook-URL tatsächlich Meldungen 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 sind. Dies kann durch Validierung der Client-ID der Anwendung erfolgen, die im X-AdobeSign-ClientId-Header übergeben wurde. Wenn die Webhook-URL diese Client-ID nicht erkennt, DARF SIE NICHT mit dem Erfolgsantwortcode antworten und Acrobat Sign stellt sicher, 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 zu 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 im HTTP-Header (X-AdobeSign-ClientId) oder in einem JSON-Antworttext mit dem Schlüssel „xAdobeClientId“ und dem Wert derselben Client-ID gesendet wird. Andernfalls wird 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;

}

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:

  1. Ein Microsoft-Konto mit Lizenz zum Erstellen von Azure Functions Applications haben
  2. Ein vorhande 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
  3. Grundkenntnisse von Javascript haben, damit Sie den Code in jeder beliebigen Sprache Ihrer Wahl verstehen und schreiben können


Schritte zum Erstellen eines Azure Functions-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 ists 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!! Illegitimier 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:

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 ists 200 * // jede Antwort im Format 2XX ist akzeptabel

            

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Ups!! Illegitimier 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 Lamda-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) {

  // Fetch client id

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

 

  //Validate it

  if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

  {

    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) {

 // Fetch client id

 var clientid = event.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

   };

     

    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- ein intuitiver Name, dass andere Administratoren sofort verstehen können, wird vorgeschlagen
  • Fläche- z. B. über ein Netzwerk das webhook Beginnen breit ist. Konto und Ihrer Gruppe sind in der Oberfläche
    • Die API unterstützt Konto-, Gruppen-, Benutzer- und Ressourcenbereiche
    • Nur ein Bereich pro webhook kann so definiert sein
  • URL: die Ziel-URL, an die Acrobat Sign die JSON-Payload ü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 Payload, das zum Triggerereignis relevant ist
    • Mehrere Ereignisse können in einem webhook enthalten sein
  • Benachrichtigungsparameter: Benachrichtigungsparameter identifizieren die Abschnitte der JSON-Ereignis-Payload, so dass Sie nur die Abschnitte des Ereignisses auswählen können, die für den betreffenden Webhook relevant sind (damit reduzieren Sie nicht notwendige Daten in Ihrer URL).

 

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

Webhook konfigurieren


Geltungsbereiche

  • Konto: Alle signierten Ereignisse, die im Kontoauslöser der Push-Vorgang auftreten?
    • Kontoadministratoren haben die Autorisierung, um alle webhooks anzuzeigen, die für das Konto/alle Gruppen definiert werden.
  • Gruppe: Alle signierten Ereignisse, die in dieser Gruppe überschneiden, den Push-Benachrichtigungen auszulösen. Gruppe verbreiteten webhooks vorhanden sind nur in einer Gruppe.
    • Gruppe dagegen nur die webhooks Administratoren, die der Gruppe verwendet wurden. Sie können Webhooks auf Kontoebene oder Webhooks, die an andere Gruppen gebunden sind, nicht anzeigen.
    • Bei Konten, bei denen Benutzer in mehreren Gruppen aktiviert sind, wird eine Option angezeigt, mit der die Gruppe festgelegt werden kann, auf die der Geltungsbereich angewendet werden soll.
  • Benutzer? Konto:? Alle signierten Ereignisse für ein Benutzerkonto push auslösen. Webhooks auf Benutzerebene können nur über die API erstellt werden.
  • Ressource Stufe webhook:? Dies ist für eine spezifische Ressource erstellt. Die Ereignisse, die mit dieser Ressource spezifisch sind, werden in die webhook URL weitergeleitet. Rohstoffverarbeitend? webhooks können über API nur erstellt werden.


URL

Ein webhook URL ist ein Server, der auf eingehende HTTPS-POSTEN-Mitteilungsmitteilungen überwacht, die ausgelöst werden, wenn Ereignisse eintreten.

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 auf dem öffentlichen Internet verfügbar sein.  
    • Beispielsweise? 127.0.0.1? und? Localhost? URIs funktioniert nicht.
    • Der URL-Endpunkt muss Port 443 überwachen.
  • Stellen Sie sicher, dass das eingehende POSTEN-Ersuchen webhook Ereignisbenachrichtigungen unterstützt und GET des Anfrage für den Überprüfungsantrag.
  • Bei der URL sollte nicht von einer Firewall blockiert werden.


Ereignisse

Nachfolgend sind die Ereignisse aufgeführt, die eine Push-Benachrichtigung an die Webhook-URL auslösen können, gruppiert nach Objekt.

Jedes Ereignis ist eine Vorlage, die der JSON-Nutzlast übertragen werden kann. (Klicken Sie auf den Namen des Ereignisses, um die Nutzlastendetails zu sehen):

  • Massenversand (früher Mega Sign): Massenversand-Ereignisse beziehen sich nur auf die Erstellung des übergeordneten Massenversand-Objekts. Die resultierenden Untergeordnete Vereinbarungen werden als Vereinbarungsereignisse verfolgt.
    • Massenversand – alle Ereignisse: Alle Massenversand-Ereignisse sind enthalten. Wenn zusätzliche Ereignisse in der Zukunft definiert sind, werden diese automatisch mit dieser Einstellung enthalten.  Die JSON-Nutzlast basiert auf der Ebene des einzelnen Ereignisses, das ausgelöst wird
    • Massenversand – erstellt: wenn einMassenversand erstellt wird
    • Massenversand – freigegeben: wenn ein Massenversand freigegeben wird
    • Massenversand – zurückgerufen: wenn ein Massenversand zurückgerufen wird
  • Webformular (früher Widgets): Webformularereignisse beziehen sich nur auf die Erstellung der Webformularvorlage. Die resultierenden Untergeordnete Vereinbarungen werden als Vereinbarungsereignisse verfolgt.
    • Widget – alle Ereignisse: Alle Webformularereignisse sind enthalten. Wenn zusätzliche Ereignisse in der Zukunft definiert sind, werden diese automatisch mit dieser Einstellung enthalten.  Die JSON-Nutzlast basiert auf der Ebene des einzelnen Ereignisses, das ausgelöst wird
    • Widget erstellt: wenn ein Webformular erstellt wird
    • Widget aktiviert: wenn ein Webformular aktiviert ist
    • Widget deaktiviert: wenn ein Webformular deaktiviert ist
    • Widget geändert: wenn ein Webformular geändert wird
    • Widget freigegeben: wenn ein Webformular freigegeben wird
    • Fehler bei Widget-Erstellung: wenn ein Webformular aufgrund eines Konvertierungsproblems automatisch abgebrochen wird


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 Vereinbarungsinformation und die Teilnehmendeninformation erhalten wollen, nicht die Dokumentinformation, wodurch ein geringeres Gesamtvolumen Ihre Webhook-URL erreicht

 

  • 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
    • - enthält alle Vereinbarungs-Teilnehmer-Informationen als Ergebnis des Ereignisses ein Teilnehmerdaten.
    • Vertrag signiertes Dokument- legt fest, dass das signierte PDF-Dokument. 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 der Webformularvorlage verknüpft sind
    • Informationen zum Widget-Teilnehmer: Informationen zu den in der Webformularvorlage definierten Teilnehmern


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 das JSON-Payload nicht erfolgreich bereit. 

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 bei Webhook-Rückrufen zu identifizieren.

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-Rückruf-URL kann nur HTTPS Port 443 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.

Fehlende Intermediate-Zertifikate

Überprüfung des Clientzertifikats

Um Zwei-Wege-SSL für einen Webhook einzurichten, müssen Administrierende eine P12- (oder PFX-)Datei hochladen, die den privaten Schlüssel enthält. Die Datei wird sicher im Nutzungskonto gespeichert und die Administrierenden 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.

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

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

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

  4. Ü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.
    Postman-Einstellungen

    • Konfigurieren Sie den HTTP-Header für x-adobesign-clientid:
    Header konfigurieren

    Senden Sie nach der Konfiguration eine POST-Anforderung an die Webhook-Rückruf-URL.

    Sie sollten eine 200-Antwort erhalten.

  5. 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 mit Enterprise-Abovariante standardmäßig aktiviert.

Administratoren können/das Webhooks Gruppenebene steuern zu erstellen, die sich nur innerhalb ihrer jeweiligen Gruppen eignen.

Zugriff auf die Webhooks-Seite kann in der linken Leiste des Admin-Menüs gefunden werden: Konto > Webhooks


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 "(drei horizontalen Linien) "rechts neben der webhooks Kopfzeile und wählen Sie "Alle Webhooks anzeigen

 

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

Das aktive webhook beginnt, Daten an das Ziel zu versenden? URL, sobald das folgende Ereignis ausgelöst wird.


Webhook deaktivieren

Durch das Deaktivieren einer webhook erfordert lediglich, dass Sie

  • 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
    • Wenn deaktiviert, wird der Status "Inaktiv webhook


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 das oder die URL geändert werden muss, muss ein neues webhook erstellt werden.

So bearbeiten Sie die Parameter eines webhook bearbeiten:

  • Navigieren Sie zur Webhooks-Seite?
  • Klicken Sie einmal auf den Webhook, den Sie bearbeiten möchten
  • Klicken Sie auf die Option "Benutzeranmeldung 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 webhook zerstört sie im System, deshalb gibt es keine Möglichkeit, eine gelöschte webhook wiederherzustellen.

Webhooks müssen nicht zuerst deaktiviert werden.

Um ein webhook zu löschen:

  • Navigieren Sie zu Webhooks
  • Wählen Sie das webhook aus, das Sie durch einfaches löschen möchten, wählen Sie sie durch Klicken
  • Klicken Sie auf die Option Löschen unter der Kopfzeile
  • Eine Herausforderung angezeigt wird, um sicherzustellen, dass Sie das webhook löschen möchten. Klicken Sie auf OK.


Bewährte Verfahren

  • 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 erhält der webhook mitunter doppelte Ereignisse. Ihre Webhook-Anwendung sollte darauf vorbereitet sein und Dopplungen nach Ereignis-ID filtern.
  • Reagieren Sie immer schnell auf Webhooks – Ihre App hat nur zehn 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.

Beispielsweise wenn signierte Dokumente verarbeitet und gespeichert werden müssen. Um sicherzustellen, dass Sie immer innerhalb von zehn Sekunden reagieren können, sollten Sie Ihre Arbeiten stets in einem separaten Thread oder asynchron mithilfe einer Warteschlange ausführen.

  • 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 nicht genau wissen, wie Sie Gleichzeitigkeit verwalten, kann Ihre App dieselben Änderungen für denselben Benutzer mehr als einmal verarbeiten.
  • Um die Vorteile von Acrobat Sign-Webhooks zu nutzen, müssen Sie eine klare Vorstellung davon haben, wie die Informationen verwendet werden sollen. Vergessen Sie nicht, Fragen wie:?

1. Welche Daten sollen in der Payload zurückgegeben werden?

2. Wer kann auf diese Informationen zugreifen??

3. Welche Entscheidungen oder der Bericht generiert werden?

  • Empfehlungen für den Empfang signierter Dokumente: 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 entfernt wurden.

ConditionalParametersTrimmed ist einArray-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, die für alle Teilnehmer einer Vereinbarung gelten, wenn ein Webhook für die betreffenden Benutzer, ihre Gruppe oder ihr Konto konfiguriert ist.

Vereinbarungsereignisse werden so verarbeitet, dass, wenn ein Webhook für den entsprechenden Teilnehmer dieses Ereignisses konfiguriert ist, eine Benachrichtigung an die betreffende Webhook-URL gesendet wird. Mit anderen Worten: Webhooks werden für Ereignisse in allen anwendbaren Vereinbarungenausgelöst, auch für Ereignisse außerhalb der Gruppe oder des Kontos, in der bzw. in dem der Webhook konfiguriert ist.

Benachrichtigungen werden nur für Ereignisse zugestellt, an denen der Teilnehmer beteiligt ist. Beispielsweise erhält der Absender einer Vereinbarung fast jede Benachrichtigung, während Empfänger Benachrichtigungen erst dann erhalten, nachdem ihre Beteiligung an der Vereinbarung begonnen hat und nur für die Ereignisse, an denen sie beteiligt sind.

Webhook-Benachrichtigungen folgen dem aktuellen Authentifizierungs- und Sichtbarkeitsmodell von Acrobat Sign selbst. Das bedeutet, dass Benutzer erst dann Zugriff auf die Vereinbarung haben, wenn die Teilnahme des Benutzers an einer Vereinbarung begonnen hat.

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.


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, solange das webhook wieder aktiviert wird.

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

Adobe-Logo

Bei Ihrem Konto anmelden