Benutzerhandbuch Abbrechen

WebHooks konfigurieren

Suchen
Adobe Sign

Adobe Sign

App öffnen
  1. Adobe Acrobat Sign-Integrationen
  2. Neue Funktionen
  3. Produktversionen und Lebenszyklus
  4. Acrobat Sign für Salesforce
    1. Paket installieren
    2. Paket konfigurieren
    3. Benutzerhandbuch
    4. Digitale Authentifizierung aktivieren
    5. Entwicklerhandbuch
    6. Erweiterter Anpassungsleitfaden
    7. Feldzuordnungs- und Vorlagenhandbuch
    8. Benutzerhandbuch für mobile App
    9. Handbuch zur Ablaufautomatisierung
    10. Document Builder-Handbuch
    11. Konfigurieren großer Dokumente
    12. Upgrade-Leitfaden
    13. Versionshinweise
    14. Häufig gestellte Fragen
    15. Leitfaden zur Fehlerbehebung
    16. Zusätzliche Artikel
  5. Acrobat Sign für Microsoft
    1. Acrobat Sign für Microsoft 365
      1. Installationshandbuch
    2. Acrobat Sign für Outlook
      1. Benutzerhandbuch
    3. Acrobat Sign für Word/PowerPoint
      1. Benutzerhandbuch
    4. Acrobat Sign für Teams
      1. Benutzerhandbuch
      2. Live Sign-Handbuch
      3. Benutzerhandbuch für Mobilversion
      4. Versionshinweise
      5. Microsoft Teams-Genehmigungen
    5. Acrobat Sign für Microsoft PowerApps und Power Automate
      1. Benutzerhandbuch
      2. Versionshinweise
    6. Acrobat Sign Connector für Microsoft Search
      1. Benutzerhandbuch
      2. Versionshinweise
    7. Acrobat Sign für Microsoft Dynamics
      1. Übersicht
      2. Dynamics Online: Installationshandbuch 
      3. Dynamics Online: Benutzerhandbuch 
      4. Dynamics On-Prem: Installationshandbuch 
      5. Dynamics On-Prem: Benutzerhandbuch
      6. Workflow-Handbuch für Dynamics
      7. Dynamics 365 for Talent
      8. Upgrade-Leitfaden
      9. Versionshinweise
    8. Acrobat Sign für Microsoft SharePoint 
      1. Übersicht
      2. SharePoint On-Prem: Installationshandbuch
      3. SharePoint On-Prem: Handbuch für Vorlagenzuordnung
      4. SharePoint On-Prem: Benutzerhandbuch
      5. SharePoint On-Prem: Versionshinweise
      6. SharePoint Online: Installationshandbuch
      7. SharePoint Online: Handbuch für Vorlagenzuordnung
      8. SharePoint Online: Benutzerhandbuch
      9. SharePoint Online: Handbuch für Webformularzuordnung
      10. SharePoint Online: Versionshinweise
  6. Acrobat Sign für ServiceNow
    1. Übersicht
    2. Installationshandbuch
    3. Benutzerhandbuch
    4. Versionshinweise
  7. Acrobat Sign für HR ServiceNow
    1. Installationshandbuch (veraltet)
  8. Acrobat Sign für SAP SuccessFactors
    1. Cockpit-Installationshandbuch (veraltet)
    2. Recruiting-Installationshandbuch (veraltet)
    3. Benutzerhandbuch für Recruiting
    4. Cloud Foundry-Installationshandbuch
    5. Versionshinweise
  9. Acrobat Sign für Workday
    1. Installationshandbuch
    2. Kurzanleitung
    3. Konfigurationstutorial
  10. Acrobat Sign für NetSuite
    1. Installationshandbuch
    2. Versionshinweise
  11. Acrobat Sign für SugarCRM
  12. Acrobat Sign für VeevaVault
    1. Installationshandbuch
    2. Benutzerhandbuch
    3. Upgrade-Leitfaden
    4. Versionshinweise
  13. Acrobat Sign für Coupa BSM Suite
    1. Installationshandbuch
  14. Acrobat Sign für Zapier
    1. Übersicht über Acrobat Sign für Zapier
    2. Unterstützte E-Signatur-Workflows
    3. Unterstützte Aktionen
    4. Erstellen automatisierter E-Signatur-Workflows
  15. Acrobat Sign-Entwicklerdokumentation
    1. Übersicht
    2. Webhooks
    3. Text-Tags

Übersicht

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:

Und so funktioniert's

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

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

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

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

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

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

Überprüfung des Intents der Webhook-URL

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

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

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

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

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

So reagierst du auf eine Webhook-Benachrichtigung

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

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") //Ersetze „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($clientid == "BGBQIIE7H253K6") //Ersetze „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") //Ersetze „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($clientid == "BGBQIIE7H253K6") //Ersetze „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

Du musst:

  1. Ein Microsoft-Konto mit Lizenz zum Erstellen von Azure Functions Applications haben
  2. Ein vorhandene Azure Function Application haben. Du kannst eine mithilfe von https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function erstellen
  3. Grundkenntnisse von JavaScript haben, damit du den Code in jeder beliebigen Sprache deiner Wahl verstehen und schreiben kannst

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

Um eine JavaScript HTTP-Triggerfunktion zu erstellen:

1. Melde dich über dein Microsoft-Konto an: https://portal.azure.com/

2. Öffne deine Azure Function Application, die auf der Registerkarte „Funktions-Apps“ angezeigt wird.

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

3. Wähle die Anwendung, in der du diese neue Funktion erstellen möchtest

4. Klicke auf Erstellen (+), um eine neue Azure-Funktion zu erstellen.

 

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

6. Klicke 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 du befolgen kannst:


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

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

Ersetze die Index.js-Datei durch Folgendes:

module.exports = function (context, req) {

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

    // Validiere, 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();

};

 

Teste das Verhalten, indem du die Anforderung simulierst:

1. Klicke auf die Schaltfläche Test ganz rechts

2. Simuliere die Anforderung

Auch wenn oben keine Antwortheader angezeigt werden, kannst du sie durch die Simulation mit Postman/DHC oder einem anderen Dienst anzeigen lassen.


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

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

Ersetze die Index.js-Datei durch Folgendes:

module.exports = function (context, req) {

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

    // Validiere, 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();

};

 

Teste das Verhalten, indem du die Anforderung simulierst

1. Klicke auf die Schaltfläche Test ganz rechts

2. Simuliere die Anforderung

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


Zur Verwendung bereit

Nachdem du das Verhalten überprüft hast, funktioniert die Webhook-URL gemäß den Acrobat Sign-Standards. Du kannst eine benutzerdefinierte Logik weiter an deine Anforderungen anpassen.

 

Erhalte die Funktions-URL

  • Klicke auf Funktions-URL abrufen

 

Kopiere die URL und verwende sie zum Erstellen von Webhooks in Acrobat Sign.

Erstellen der AWS Lambda-Funktion

Um eine AWS Lambda-Funktion zu erstellen, melde dich bei deiner AWS Management Console an und wähle den AWS Lambda-Dienst aus der Liste der Dienste aus.

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

  • Wähle auf der Seite mit der neuen AWS Lambda-Funktion unter Code-Eingabetyp die Option Code inline bearbeiten aus und behalte „index.handler“ als Handler bei.
  • Füge 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: Beachte auch, dass dasselbe Verhalten für clientID erwartet wird, wenn die Webhook-URL POST-Benachrichtigungen empfängt.

    Gehe wie in einem der beiden Fälle vor:

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

    •  Übergib 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
      Ersetze 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“) //Ersetze „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: Übergib 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

Ersetze 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“) //Ersetze „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");

  }

}

  • Speichere 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ähle in der AWS Management Console das API Gateway aus den AWS-Diensten aus und klicke auf die Schaltfläche API erstellen.

  • Wähle auf der Seite Neue API erstellen die Option Neue API aus und gib Webhooks als API-Name ein.
  • Klicke auf die Schaltfläche API erstellen.
  • Wähle die Dropdown-Liste Aktionen und dann die Option Ressource erstellen aus.
  • Aktiviere die OptionAls Proxyressource konfigurieren und gib validate als Ressourcenname und {proxy+} in den Ressourcenpfad ein.
  • Lasse die Option API Gateway CORS aktivieren deaktiviert und klicke auf die Schaltfläche Ressource erstellen.
  • Lasse die Option Lambda-Funktion-Proxy als Integrationstyp ausgewählt und wähle in der Dropdown-Liste Lambda-Region die Region aus, in der du die Lambda-Funktion erstellt hast (dies ist wahrscheinlich dieselbe Region, in der du das API Gateway erstellst).
  • Gib validate als Lambda-Funktion ein und klicke auf die Schaltfläche Speichern.
  • Klicke 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ähle in der Dropdown-Liste Aktionen die Option API bereitstellen aus.
  • Wähle unter Bereitstellungsphase die Option [Neue Phase] aus und gib unter Phasenname Produktion oder einen beliebigen anderen Wert zur Identifizierung der betreffenden Phase ein.
  • Klicke auf die Schaltfläche Bereitstellen.

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

Notiere dir diese URL, da du sie als URL für den Echtzeit-Webhook eingeben musst.

Zur Verwendung bereit

Fertig. Verwende diese URL oben mit dem Anhang „/{nodeJSfunctionName}“ als Webhook-URL in der POST /webhooks API-Anforderung.  Nachdem du das Verhalten überprüft hast, funktioniert die Webhook-URL gemäß den
Acrobat Sign-Standards. Du kannst die benutzerdefinierte Logik deinen 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 Administrierende sofort verstehen können.
  • Umfang: Welches Ausmaß eines Netzwerks 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 du nur die Abschnitte des Ereignisses auswählen kannst, die für den betreffenden Webhook relevant sind (damit reduzierst du nicht notwendige Daten, die an deine URL gesendet werden).

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

Hinweis:

Konfiguriere 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 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. Du kannst die Webhooks auf Kontoebene oder die Webhooks, die an andere Gruppen gebunden sind, nicht sehen.
    • 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.

Du benötigst diese URL, damit du dein Webhook Ereignisse abonnieren kannst.

  • 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).
  • Stelle 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 findest du 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 findest du 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
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
   
Nur über die API verfügbare Vereinbarungs-Webhooks
N/A AGREEMENT_EXPIRATION_UPDATED
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

 

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 dir, die JSON-Nutzlast nur bestimmten Elementen des Ereignisses anzupassen.

Bei einem Vereinbarungsteilnehmende ersetzt-Ereignis könntest du zum Beispiel nur die Vereinbarungsinformationen und die Teilnahmeinformationen erhalten wollen, nicht die Dokumentinformationen, wodurch sich das Gesamtvolumen der an deine 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. 

Verwende Zwei-Wege-SSL zur Authentifizierung des Clients (Acrobat Sign) und des Listening-Service, um sicherzustellen, dass nur Acrobat Sign deine 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.

Weitere Informationen zu den SSL-/TSL-Anforderungen.

Im Folgenden findest du 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.

Du kannst 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.

Gib 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: Verwende 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: Installiere die Intermediate-Zertifikate auf dem Webhook-Rückrufserver.

Weitere Informationen findest du 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 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.

  1. Stelle sicher, dass Zwei-Wege-SSL aktiviert ist.

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

    Stelle 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:

    Du kannst mit Postman eine POST-Anfrage an die Webhook-Rückruf-URL durchführen. Du solltest ein ähnliches Ergebnis erhalten.

  2. Überprüfe das Clientzertifikat lokal.

    Die Clientanmeldedaten können entweder ein selbstsigniertes Zertifikat oder ein von einer Zertifizierungsstelle ausgestelltes Zertifikat sein. Du musst 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). 

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

    Achtung:

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

  3. Erstelle ein selbstsigniertes Clientzertifikat (optional).

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

    Zum Generieren eines selbstsignierten Clientzertifikats verwendest du den folgenden openssl-Befehl:

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

    Vorsicht:

    Achte darauf, dass die resultierenden Dateien geheim bleiben, da es sich um deine selbstsignierten CA-Zertifikate handelt.

    Generiere als Nächstes die P12-Datei des Clients:

    1. Generiere einen privaten Schlüssel für den SSL-Client:

      openssl genrsa -out client.key 2048

    2. Verwende den privaten Schlüssel des Clients, um eine Zertifikatanforderung zu generieren:

      openssl req -new -key client.key -out client.req

    3. Stelle 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. Konvertiere 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. Entferne den privaten Clientschlüssel, das Clientzertifikat und die Clientanforderungsdateien, da die PKCS12-Datei alles enthält, was du benötigst.

      rm client.key client.cer client.req

  4. Überprüfe das Clientzertifikat auf dem Remote-Server.

    • Lade mit Postman die Client-PFX-Datei in Einstellungen > Zertifikate hoch.
    • Wähle Zertifikat hinzufügen aus, um das Clientzertifikat hinzuzufügen.
    Postman-Einstellungen

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

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

    Du solltest eine 200-Antwort erhalten.

  5. Warum lehnt Acrobat Sign meine PFX-Datei ab, obwohl ich sie mit Postman überprüft habe?

    Wenn du den oben beschriebenen Vorgang zur Überprüfung der PFX-Datei ausgeführt hast 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.

    Verwende 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:

  • Klicke auf das Symbol Optionen (drei horizontalen Linien) rechts neben der Webhooks-Kopfzeile und wähle Alle Webhooks anzeigen aus

 

  • Klicke einmal auf den inaktiven Webhook, um ihn auszuwählen
    • Dadurch erscheinen die Optionen für den Webhook direkt unter der Kopfzeile
  • Klicke 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, folge einfach den folgenden Schritten:

  • Navigiere zur Webhooks-Seite
  • Wähle den Webhook, den du deaktivieren möchtest, durch einfaches Klicken aus.
  • Aktiviere 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 bearbeitest du die Parameter eines Webhooks:

  • Navigiere zur Webhooks-Seite
  • Klicke einmal auf den Webhook, den du bearbeiten möchtest
  • Klicke auf die Option anzeigen/bearbeiten unter der Kopfzeile

 

  • Nimm die erforderlichen Änderungen vor und klicke 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:

  • Navigiere zu Webhooks
  • Wähle den Webhook aus, den du durch einfaches Klicken löschen möchtest.
  • Klicke auf die Option Löschen unter der Kopfzeile
  • Es wird eine Warnmeldung angezeigt, um sicherzustellen, dass du den Webhook wirklich löschen möchtest. Klicke auf OK.

Bewährte Verfahren

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

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

Zu berücksichtigende Punkte...

JSON-Größenbeschränkung

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

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

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

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

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

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

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

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

Webhook-Benachrichtigungen

Acrobat Sign-Webhooks senden Benachrichtigungen, 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 Vereinbarungen ausgelö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, sobald der Webhook wieder aktiviert wird.

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

Schneller und einfacher Hilfe erhalten

Neuer Benutzer?

Hilfreiche Links

Alle Abos anzeigen Abos verwalten
Hilfreiche Links einblenden
Hilfreiche Links ausblenden

Rechtliche Hinweise    |    Online-Datenschutzrichtlinie