Webhooks configureren

Zoeken

Overzicht

Een webhook is een door de gebruiker gedefinieerde HTTPS-callback die wordt geactiveerd wanneer een bepaalde gebeurtenis plaatsvindt op de bronsite (in dit geval Adobe Acrobat Sign).

In feite is een webhook niets anders dan een webservice die HTTPS-POST-verzoeken accepteert van een bron. Een webhook is dus een REST-service die gegevens of een gegevensstroom accepteert.

Webhooks zijn bedoeld voor service-to-service communicatie in een Push-model.

Wanneer zich een activerende gebeurtenis voordoet, construeert Acrobat Sign een HTTPS-POST met een JSON-body en levert deze aan de opgegeven URL.

 

Het gebruik van webhooks biedt een aantal voordelen in vergelijking met de voorgaande Callback-methode, zoals:

  • Beheerders kunnen hun eigen webhooks inschakelen zonder Acrobat Sign-ondersteuning voor het weergeven van de callback-URL
  • Webhooks zijn beter betreffende 'versheid' van gegevens, de efficiëntie van communicatie en beveiliging. Geen polling vereist
  • Met webhooks wordt het gebruik van verschillende bereiken eenvoudiger (Account/Groep/Gebruiker/Bron). 
  • Webhooks bieden een modernere API-oplossing en een eenvoudigere configuratie van hedendaagse toepassingen
  • U kunt meerdere webhooks per bereik configureren (Account/Groep/Gebruiker/Bron), terwijl callbacks uniek moesten zijn
  • Bij webhooks kunt u specifiek aangeven welke gegevens worden geretourneerd. Bij callbacks is dit een 'alles of niets'-optie
  • De metagegevens die zijn opgenomen in een webhook, kunnen worden geconfigureerd (standaard of gedetailleerd)
  • Webhooks kunnen veel eenvoudiger worden gemaakt, bewerkt of, indien nodig, uitgeschakeld, omdat de gebruikersinterface volledig binnen de controle van de beheerder valt.
Opmerking:

Dit document is voornamelijk gericht op de webhooks-UI in de Acrobat Sign-internettoepassing (voorheen Adobe Sign).

Ontwikkelaars die meer willen weten over API kunnen hier de gewenste informatie vinden:


Het gebruik

Beheerders moeten eerst een webhookservice hebben waarmee binnenkomende pushmeldingen van Acrobat Sign worden geaccepteerd. Er zijn in dit opzicht veel opties en zolang de service POST- en GET-verzoeken kan accepteren, zal de webhook succesvol zijn.

Zodra de service is ingesteld, kan een Acrobat Sign-beheerder een nieuwe webhook maken via de Webhook-interface in het menu Account van de Acrobat Sign-site.

Beheerders kunnen de webhook zodanig configureren dat deze wordt geactiveerd voor afspraken, webformulieren of 'In bulk verzenden'-gebeurtenissen.

Het bereik van webhook een heel account of afzonderlijke groepen omvatten. Dit gebeurt via de beheerinterface. De bereiken Gebruiker en Bron kunnen ook worden ingesteld via de API

Het type gegevens dat via een pushmelding naar de URL wordt gestuurd, kan worden geconfigureerd en kan bijvoorbeeld informatie bevatten over de overeenkomst, de deelnemer, het ondertekende document, enzovoort.

Nadat de webhook is geconfigureerd en opgeslagen, zal Acrobat Sign telkens een nieuw JSON-object naar de gedefinieerde URL sturen via een pushmelding. Dit gebeurt telkens wanneer de triggergebeurtenis plaatsvindt. U hoeft de webhook niet voortdurend te bewerken of te controleren, tenzij u de criteria voor triggergebeurtenissen of de JSON-payload wilt wijzigen.


Verificatie van de bedoeling van de webhook -URL

Voordat een webhook kan worden geregistreerd, controleert Acrobat Sign of de webhook-URL in de registratieaanvraag daadwerkelijk is bedoeld om meldingen te ontvangen. Wanneer Acrobat Sign een nieuwe aanvraag voor webhookregistratie ontvangt, wordt dan ook eerst een verificatieaanvraag gestuurd naar de webhook-URL. Dit verificatieverzoek is een HTTPS GET-aanvraag die naar de webhook-URL is verzonden. Deze aanvraag heeft een aangepaste HTTP-header X-AdobeSign-ClientId. De waarde in deze header is ingesteld op de client-ID (applicatie-ID) van de API-applicatie die de aanvraag voor het maken/registreren van de webhook indient. Voordat een webhook kan worden geregistreerd, moet de webhook-URL aan dit verzoek voldoen met een 2XX-responscode. Bovendien moet dezelfde waarde voor de client-ID worden teruggestuurd op een van de volgende twee manieren.

  • Ofwel in een X-AdobeSign-ClientId-responsheader. Dit is dezelfde koptekst die was doorgegeven in de oorspronkelijke aanvraag en die in de respons moet worden 'teruggekaatst'.
  • Ofwel in de JSON-hoofdtekst van de respons met de sleutel xAdobeSignClientId en de waarde die gelijk is aan de client-ID die in de koptekst van de aanvraag was verzonden.

De webhook wordt alleen geregistreerd bij een succesvolle respons (2XX-responscode) en validatie van de client-ID in de kop- of hoofdtekst van de respons. Het doel van deze verificatieaanvraag is om aan te tonen dat uw webhook-URL ook daadwerkelijk meldingen wil ontvangen op de desbetreffende URL. Als u per ongeluk een verkeerde URL hebt ingevoerd, reageert de URL niet correct op de verificatieaanvraag en stuurt Acrobat Sign geen meldingen meer naar die URL. Daarnaast kan de webhook-URL ook bevestigen dat de URL alleen meldingen ontvangt via de webhooks die zijn geregistreerd bij een bepaalde toepassing. Hiervoor moet u de client-ID van de toepassing valideren die wordt doorgegeven in de X-AdobeSign-ClientId-header. Als deze client-ID niet wordt herkend door de webhook-URL, MOET deze NIET reageren met de antwoordcode voor succes. Acrobat Sign zal er in dat geval voor zorgen dat de URL niet als webhook wordt geregistreerd.

Verificatie van de webhook-URL-aanroep wordt in de volgende gevallen uitgevoerd:

  • Bij registratie van de webhook: als de verificatie van de webhook-URL-aanroep mislukt, wordt de webhook niet gemaakt
  • Bij het bijwerken van de webhook van NIET-ACTIEF naar ACTIEF: als de verificatie van de webhook-URL-aanroep mislukt, wordt de webhook niet gewijzigd naar ACTIEF

Reageren op een webhookmelding

Acrobat Sign voert een impliciete verificatie van de intentie uit in elk webhookmeldingsverzoek dat naar de webhook-URL wordt verzonden. Zo bevat elk webhookmeldings-HTTPS-verzoek ook de aangepaste HTTP header genaamd X-AdobeSign-ClientId. De waarde van deze header is de client-ID (Application ID) van de toepassing waarmee de webhook is gemaakt De levering van de webhookmelding is alleen succesvol als het antwoord voor succesvolle levering (2XX antwoordcode) wordt geretourneerd en de client-ID wordt verzonden in de HTTP header (X-AdobeSign-ClientId)  of in een JSON-antwoordtekst met sleutel als xAdobeSignClientId en waarde als dezelfde client-ID, anders proberen we de melding opnieuw naar de webhook-URL te sturen totdat de nieuwe pogingen zijn uitgeput.

Zoals hierboven vermeld, moet de waarde van de client-ID in de koptekst 'X-AdobeSign-ClientId' die is opgenomen in elke meldingsaanvraag van Sign, op een van de volgende twee manieren worden 'teruggekaatst':

1. HTTP-koptekst X-AdobeSign-ClientId en de waarde van deze client-ID

Voorbeeld van Javascript-code voor het ophalen, valideren en retourneren van de client-ID naar de koptekst van het antwoord

//Client-ID ophalen

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

 

//Valideren

if (clientid ==="BGBQIIE7H253K6") //Vervang de waarde 'BGBQIIE7H253K6' door de client-ID van de toepassing waarmee de webhook is gemaakt

{

    //Retourneren in de koptekst van de respons

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

    response.status = 200;  // standaardwaarde

}

Voorbeeld van PHP-code voor het ophalen, valideren en retourneren van de client-ID naar de koptekst van het antwoord

 

<?php

//Client-ID ophalen

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valideren

if($clientid == "BGBQIIE7H253K6") //Vervang de waarde 'BGBQIIE7H253K6' door de client-ID van de toepassing waarmee de webhook is gemaakt

{

    //Retourneren in de koptekst van de respons

   header("X-AdobeSign-ClientId:$clientid");

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

}

?>

 


2. JSON-hoofdtekst van de respons met de sleutel xAdobeSignClientId en de waarde van dezelfde client-ID

Voorbeeld van Javascript-code voor het ophalen, valideren en retourneren van de client-ID naar de hoofdtekst van hat antwoord

//Client-ID ophalen

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

 

 

//Valideren

if (clientid ==="BGBQIIE7H253K6") //Vervang de waarde 'BGBQIIE7H253K6' door de client-ID van de toepassing waarmee de webhook is gemaakt

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Client-ID retourneren in de hoofdtekst van de respons

                       };

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

    response.body = responseBody;

    response.status = 200;

}

Voorbeeld van PHP-code voor het ophalen, valideren en retourneren van de client-ID naar de hoofdtekst van de respons

<?php

//Client-ID ophalen

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valideren

if($clientid == "BGBQIIE7H253K6") //Vervang de waarde 'BGBQIIE7H253K6' door de client-ID van de toepassing waarmee de webhook is gemaakt

{

    //Retourneren in de hoofdtekst van de respons

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

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

   echo json_encode($body);

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

}

?>

Voorbeeld van JSON-hoofdtekst van de respons

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Voorwaarden

U hebt het volgende nodig:

  1. Een Microsoft-account met een licentie om Azure Functions-toepassingen te maken
  2. Een bestaande Azure Function-toepassing. U kunt deze maken met behulp van https://docs.microsoft.com/nl-nl/azure/azure-functions/functions-create-first-azure-function 
  3. Standaardkennis van Javascript, zodat u de code in een taal van uw keuze kunt begrijpen en schrijven


Stappen voor het maken van een Azure Functions-trigger die fungeert als Acrobat Sign-webhook

Een Javascript HTTP-triggerfunctie maken:

1. Meld u aan via uw Microsoft-account https://portal.azure.com/

2. Open de Azure Functie-applicatie die wordt weergegeven op het tabblad Functie-apps.

Hiermee wordt uw lijst met Azure Function-toepassingen geopend:

3. Kies de toepassing waarin u deze nieuwe functie wilt maken

4. Klik op de knop Maken (+) om een nieuwe Azure-functie te maken

 

5. Selecteer Webhook + API als scenario en Javascript als taal

6. Klik op Deze functie maken

Er wordt een nieuwe functie gemaakt waarmee een binnenkomende API-aanvraag kan worden verwerkt.


Logica toevoegen voor registratie van de Acrobat Sign-webhook

Voordat een webhook kan worden geregistreerd, controleert Acrobat Sign of de webhook-URL in de registratieaanvraag daadwerkelijk is bedoeld om meldingen te ontvangen. Wanneer Acrobat Sign een nieuwe aanvraag voor webhookregistratie ontvangt, wordt dan ook eerst een verificatieaanvraag gestuurd naar de webhook-URL. Hierbij gaat het om een HTTPS GET-aanvraag die naar de webhook-URL wordt gestuurd met de aangepaste HTTP-header X-AdobeSign-ClientId. De waarde in deze header is ingesteld op de client-ID van de toepassing die de aanvraag voor het maken/registreren van de webhook indient. Voordat een webhook kan worden geregistreerd, moet de webhook-URL aan dit verzoek voldoen met een 2XX-responscode. Bovendien moet dezelfde waarde voor de client-ID worden teruggestuurd op een van de volgende twee manieren.

U hebt twee opties:


Optie 1: De client-ID in X-AdobeSign-ClientId doorgeven als koptekst van de respons

Geef de X-AdobeSign-ClientId door in de koptekst van de respons. Dit is dezelfde koptekst die was doorgegeven in de oorspronkelijke aanvraag en die in de respons moet worden 'teruggekaatst'.

Vervang het bestand Index.js door het volgende:

module.exports = function (context, req) {

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

    // Bevestigen dat de binnenkomende ClientID ook echt is

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // elke 2XX-respons is acceptabel

            body: "Melding geaccepteerd",

            headers : {

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

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Oeps!! Ongeldige aanroep geïdentificeerd"

        };

    }

    context.done();

};

 

Test het gedrag door de aanvraag na te bootsen:

1. Klik op de knop Test in de rechterhoek

2. Boots de aanvraag na

Hoewel antwoordheaders hierboven niet worden weergegeven, kunt u het bekijken door nabootsing via postman/DHC of een andere dienst.


Optie 2: De client-ID doorgeven in de hoofdtekst van het antwoord met de sleutel xAdobeSignClientId

In de JSON-hoofdtekst van de respons met de sleutel xAdobeSignClientId en de waarde die gelijk is aan de client-ID die in de koptekst van de aanvraag was verzonden.

Vervang het bestand Index.js door het volgende:

module.exports = function (context, req) {

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

    // Bevestigen dat de binnenkomende ClientID ook echt is

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // elke 2XX-respons is acceptabel

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Oeps!! Ongeldige aanroep geïdentificeerd"

        };

    }

    context.done();

};

 

Test het gedrag door de aanvraag na te bootsen

1. Klik op de knop Test in de rechterhoek

2. Boots de aanvraag na

Merk op dat hetzelfde gedrag voor clientID wordt verwacht wanneer de webhook-URL een POST-melding ontvangt. 


Klaar voor gebruik

Nadat u het gedrag hebt geverifieerd, is de webhook-URL functioneel volgens de Acrobat Sign-normen. U kunt de aangepaste logica verder bijwerken op basis van uw vereisten.

 

De functie-URL ophalen

  • Klik op Functie-URL ophalen

 

Kopieer de URL en gebruik deze om webhooks te maken in Acrobat Sign.

De AWS Lambda-functie maken

Om een AWS Lambda-functie te maken meldt u zich aan bij uw AWS Management Console en selecteert u de AWS Lambda-service in de lijst met services.

  • Klik op Een Lambda-functie maken met de optie Nieuw ontwerpen
  • Voer op de pagina Functie configureren de functienaam lambdaWebhooks in en selecteer Node.js 4.3 als Runtime
  • Kies voor de Rol een bestaande rol of maak een nieuwe rol op basis van sjablonen
    • Als u hebt gekozen voor  Nieuwe rol maken op basis van sjablonen, voert u een rolnaam in (bijv. rol-lamda) en selecteert u Vereenvoudigde microservices-machtigingen in de lijst Beleidsjablonen
  • Klik op de knop Functie maken 

  • Selecteer op de nieuwe AWS lambda-functiepagina Code inline bewerken als Type code-invoer, bewaar de index.handler als Handler.
  • Logica toevoegen om de Acrobat Sign-webhook te registreren

    Voordat een webhook kan worden geregistreerd, controleert Acrobat Sign of de webhook-URL in de registratieaanvraag daadwerkelijk is bedoeld om meldingen te ontvangen. Wanneer Acrobat Sign een nieuwe aanvraag voor webhookregistratie ontvangt, wordt dan ook eerst een verificatieaanvraag gestuurd naar de webhook-URL. Hierbij gaat het om een HTTPS GET-aanvraag die naar de webhook-URL wordt gestuurd met de aangepaste HTTP-header X-AdobeSign-ClientId. De waarde in deze header is ingesteld op de client-ID van de toepassing die de aanvraag voor het maken/registreren van de webhook indient. Voordat een webhook kan worden geregistreerd, moet de webhook-URL aan dit verzoek voldoen met een 2XX-responscode. Bovendien moet dezelfde waarde voor de client-ID worden teruggestuurd op een van de volgende twee manieren. Merk op dat hetzelfde gedrag voor clientID wordt verwacht wanneer de webhook-URL een POST-melding ontvangt. 

    Volg een van de twee gevallen:

    Geval 1: Client-ID doorgeven in X-AdobeSign-ClientId als koptekst van de respons

    •  Geef de X-AdobeSign-ClientId door in de koptekst van de respons. Dit is dezelfde koptekst die was doorgegeven in de oorspronkelijke aanvraag en die in de respons moet worden 'teruggekaatst'.

      Codefragment
      In het index.js-bestand vervangt u het automatisch gegenereerde codefragment door de volgende code:

Voorbeeld van de JS-code van de node om de client-ID op te halen, deze te valideren en vervolgens terug te sturen naar de koptekst van de respons

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

  // Client-ID ophalen

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

 

 //Valideren

  if (clientid =="BGBQIIE7H253K6") //Vervang 'BGBQIIE7H253K6' door de client-ID van de toepassing waarmee de webhook is gemaakt

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! illegitimate call");

  }

}

 

Geval 2: Client-ID doorgeven in de hoofdtekst van de respons met de sleutel xAdobeSignClientId

In de JSON-hoofdtekst van de respons met de sleutel xAdobeSignClientId en de waarde die gelijk is aan de client-ID die in de koptekst van de aanvraag was verzonden.

 

Codefragment

Vervang het bestand Index.js door het volgende:

Voorbeeld van de JS-code van de node om de client-ID op te halen, deze te valideren en vervolgens terug te sturen naar de koptekst van de respons

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

 // Client-ID ophalen

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

  

 //Valideren

 if (clientid =="BGBQIIE7H253K6") //Vervang 'BGBQIIE7H253K6' door de client-ID van de applicatie waarmee de webhook is gemaakt

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Opps!! illegitimate call");

  }

}

  • Sla de functie op. Lambda-functie is gemaakt en we zijn bijna klaar om deze te gebruiken in een realtimewebhook

 

De AWS API-gateway configureren

Om deze Lambda openbaar toegankelijk te maken via een HTTP-methode moeten we de AWS API Gateway configureren met onze functie (hierboven gemaakt) als de back-end voor de API.

Selecteer in de AWS Management Console de API-gateway van de AWS-services en klik op de knop API maken 

  • Selecteer op de pagina Nieuwe API maken Nieuwe API en voer webhooks in als de API-naam.
  • Klik op de knop API maken 
  • Selecteer de vervolgkeuzelijst Acties en selecteer de optie Bron maken
  • Selecteer de optie Configureren als proxybron en voer valideren in bij Bronnaam en {proxy+} in het Bronpad
  • Selecteer de optie API Gateway CORS inschakelen niet en klik op de knop Bron maken 
  • Houd de Lambda-functieproxy geselecteerd als integratietype en selecteer het gebied waar u de Lambda-functie hebt gemaakt in de vervolgkeuzelijst Lambda-gebied (waarschijnlijk is dat hetzelfde gebied waar u de API-gateway maakt).
  • Voer valideren in als de Lambda-functie en klik op de knop Opslaan
  • Selecteer in het pop-upvenster Toestemming toevoegen aan Lambda-functie OK

Als alle bovenstaande stappen correct zijn uitgevoerd, ziet u zoiets als dit:

API implementeren

De volgende stap is het implementeren van deze API, zodat deze klaar is voor gebruik.

  • Selecteer in de vervolgkeuzelijst Acties API implementeren
  • Selecteer [Nieuw stadium] in de Implementatiefase en voer prod (of iets anders waarmee u dit stadium wilt identificeren) in de Stadiumnaam in
  • Klik op de knop Implementeren 

API is nu klaar voor gebruik en u kunt de aanroep-URL vinden in het blauwe vak, zoals hieronder weergegeven:

Let op deze URL, want u moet deze invoeren als uw realtimewebhook-URL.

 

Klaar voor gebruik

Het is gereed. Gebruik deze bovenstaande URL met "/{nodeJSfunctionName}" toegevoegd als webhook-url in POST /webhooks API-verzoek.  Nadat u het gedrag hebt geverifieerd, is de webhook-URL functioneel volgens de
Acrobat Sign-normen. U kunt de aangepaste logica verder bijwerken/toevoegen volgens uw vereisten.


Configuratieopties

Bij de configuratie van de webhook moet u vijf elementen definiëren:

  • Naam: gebruik een intuïtieve naam die eenvoudig wordt begrepen door andere beheerders
  • Bereik: hoe groot is het 'vangnet' van de webhook Account en Groep zijn beschikbaar in de interface
    • De API biedt ondersteuning voor de bereiken Account, Groep, Gebruiker en Bron
    • Er kan slechts één bereik per webhook worden gedefinieerd
  • URL: de doel-URL waarnaar Acrobat Sign de JSON-payload heeft gepusht
  • Gebeurtenissen: de trigger die ervoor zorgt dat Acrobat Sign de JSON bouwt en naar de URL pusht
    • Elke gebeurtenis bouwt een andere lading die relevant is voor de activeringsgebeurtenis
    • Een webhook kan meerdere gebeurtenissen bevatten
  • Meldingsparameters: met de meldingsparameters worden de secties van de JSON-lading voor de Gebeurtenis geïdentificeerd, zodat u alleen die secties van de Gebeurtenis kunt selecteren die voor deze webhook belangrijk zijn (wat leidt tot minder onnodige gegevens in uw URL).

 

Zodra de webhook volledig is gedefinieerd, klikt u op Opslaan, waarna de webhook direct kan reageren op activeringsgebeurtenissen. 

Opmerking:

Configureer uw webhook-URL om te reageren op de webhookverificatie en webhookmeldingsverzoeken volgens het verificatieprotocol dat hierboven is uitgelegd. De client-ID (toepassings-ID) die wordt verzonden naar webhooks die zijn gemaakt met de Acrobat Sign-webtoepassing, is - UB7E5BXCXY

De webhook configureren


Bereiken

  • Account: de pushmelding wordt geactiveerd door alle geabonneerde gebeurtenissen in de account 
    • Accountbeheerders kunnen alle webhooks bekijken die zijn gedefinieerd voor de account/alle groepen.
  • Groep: de pushmelding wordt geactiveerd door alle geabonneerde gebeurtenissen in de desbetreffende groep Webhooks met het bereik Groep bestaan slechts in één groep.
    • Groepsbeheerders kunnen alleen die webhooks zien die aan hun groep zijn toegewezen. Ze kunnen geen webhooks of webhooks gebonden aan andere groepen.
    • Accounts waarvoor gebruikers in meerdere groepen zijn ingeschakeld, zien de optie om de groep in te stellen waarop het bereik moet worden toegepast.
  • Gebruikersaccount: de pushmelding wordt geactiveerd door alle gebeurtenissen met aanmelding in een gebruikersaccount. Webhooks op gebruikersniveau kunnen alleen via een API worden gemaakt.
  • Webhook op bronniveau: dergelijke webhooks worden gemaakt voor een specifieke bron. De gebeurtenissen die specifiek zijn voor deze bron, worden via een pushmelding naar de webhook-URL gestuurd. Webhooks op bronniveau kunnen alleen worden gemaakt via een API.


URL

Een webhook-URL is een server die luistert naar binnenkomende HTTPS POST-meldingen die worden geactiveerd wanneer bepaalde gebeurtenissen plaatsvinden.

U hebt deze URL nodig om uw webhook bij gebeurtenissen aan te melden.

  • De client moet een HTTPS-URL opnemen waarnaar Acrobat Sign een POST-melding kan sturen. Deze URL moet openbaar zijn op internet.  
    • Zo zullen 127.0.0.1 en localhost-URI's bijvoorbeeld niet functioneren.
    • Het URL-eindpunt moet luisteren op poort 443.
  • Controleer of de webhook ondersteuning biedt voor POST-aanvragen bij inkomende gebeurtenismeldingen en voor GET-aanvragen bij de verificatieaanvraag.
  • De URL mag niet worden geblokkeerd door een firewall.


Gebeurtenissen

Hieronder staan de gebeurtenissen die een pushmelding aan de webhook-URL kunnen activeren, gegroepeerd per object.

Elke gebeurtenis heeft een sjabloon met de JSON-lading die kan worden geleverd. (Klik op de naam van de gebeurtenis om de lading weer te geven):

  • In bulk verzenden (voorheen Mega Sign) - In bulk verzenden-gebeurtenissen hebben alleen betrekking op het maken van het bovenliggende object voor In bulk verzenden. De resulterende onderliggende overeenkomsten worden bijgehouden als overeenkomstgebeurtenissen. 
    • In bulk verzenden: alle gebeurtenissen voor In bulk verzenden zijn inbegrepen. Als er in de toekomst extra gebeurtenissen worden gedefinieerd, worden deze automatisch via deze instelling opgenomen.  De JSON-lading is gebaseerd op de afzonderlijke gebeurtenis die wordt geactiveerd
    • In bulk verzenden gemaakt: wanneer een In bulk verzenden wordt gemaakt
    • In bulk verzenden gedeeld: wanneer een In bulk verzenden wordt gedeeld
    • In bulk verzenden intrekken: wanneer een In bulk verzenden wordt ingetrokken
  • Webformulier (voorheen Widgets): webformuliergebeurtenissen hebben alleen betrekking op het maken van de webformuliersjabloon. De resulterende onderliggende overeenkomsten worden bijgehouden als overeenkomstgebeurtenissen.
    • Alle gebeurtenissen van widget: alle webformuliergebeurtenissen zijn inbegrepen. Als er in de toekomst extra gebeurtenissen worden gedefinieerd, worden deze automatisch via deze instelling opgenomen.  De JSON-lading is gebaseerd op de afzonderlijke gebeurtenis die wordt geactiveerd
    • Widget gemaakt: wanneer een webformulier wordt gemaakt
    • Widget ingeschakeld: wanneer een webformulier is ingeschakeld
    • Widget uitgeschakeld: wanneer een webformulier is uitgeschakeld
    • Widget gewijzigd: wanneer een webformulier wordt gewijzigd
    • Widget gedeeld: wanneer een webformulier wordt gedeeld
    • Widget maken mislukt: wanneer een widget automatisch wordt geannuleerd vanwege een conversieprobleem


Meldingsparameters

Met meldingsparamters kunt u de JSON-lading aanpassen aan de specifieke elementen van de gebeurtenis.

Bij de gebeurtenis Overeenkomstdeelnemer vervangen wilt u bijvoorbeeld misschien alleen de elementen Overeenkomstgegevens en Deelnemersgegevens opnemen, en niet Documentgegevens. Zo houdt u ook de totale inhoud van uw webhook-URL beperkt

 

  • Overeenkomst
    • Agreement Info: gedetailleerde agreement die de status van de agreement op het moment van de activerende gebeurtenis wordt gebaseerd
    • Agreement Document Info: bevat alle document die als gevolg van de gebeurtenis is gegenereerd
    • Gegevens overeenkomstdeelnemer: bevat alle deelnemergegevens als gevolg van de gebeurtenis
    • Document met ondertekende overeenkomst: de ondertekende PDF. 
      • Van toepassing op de gebeurtenissen Agreement Workflow Completed en Agreement All
  • In bulk verzenden
    • Info over In bulk verzenden: gedetailleerde informatie over het object In bulk verzenden dat de gebeurtenis heeft geactiveerd
  • Webformulier
    • Widgetinfo: gedetailleerde informatie over het webformulier dat de gebeurtenis heeft geactiveerd
    • Widget-documentinformatie: de documentinformatie die is gekoppeld aan de webformuliersjabloon
    • Widget-deelnemersinformatie: informatie over de gedefinieerde deelnemers in de webformuliersjabloon


Tweezijdige SSL-verificatie

Tweerichtings-SSL, vaak Client-Side SSL of wederzijdse TLS genoemd, is een SSL-modus waarbij zowel de server als de client (webbrowser) certificaten presenteren om zichzelf te identificeren.

Accountbeheerders kunnen een 'client-side'-certificaat configureren op de pagina Beveiligingsinstellingen.

Acrobat Sign verifieert de SSL-certificaten bij het leveren van payloads aan de webhook-URL. Als een webhook de SSL-certificaatverificatie niet doorstaat, wordt er geen JSON-lading geleverd. 

Gebruik tweezijdige SSL-verificatie om de client (Acrobat Sign) te verifiëren en als listening-service om er zeker van te zijn dat uw webhook-URL alleen bereikbaar is voor Acrobat Sign. 

Als de webhook is gemaakt door een partnerapplicatie, gebruikt de webhook een clientcertificaat (indien beschikbaar) van het account van de partnerapplicatie om zichzelf te identificeren bij het maken van webhook-oproepen.

Hieronder vindt u de meest voorkomende vragen voor zowel het verificatieproces van de webserver als de verificatie van de clientcertificering.

Webserververificatie

Tijdens de registratie van een webhook verifieert Acrobat Sign de URL van de webhookserver.

Klanten kunnen de webhook niet registreren als de verbinding met de terugbel-URL van de webhook niet kan worden voltooid met Acrobat Sign.

Nee.

De webhookcallback-URL kan alleen HTTPS zijn op poort 443.

Acrobat Sign blokkeert het uitgaande HTTPS-verkeer naar alle andere poorten.

Een goede manier om het servercertificaat te verifiëren is door de DigiCert® SSL-installatiediagnosetool te gebruiken.

Voer alleen de hostnaam in, bijvoorbeeld: www.digicert.com

Veelvoorkomende problemen zijn:

  • Probleem: een niet-vertrouwd CA- of zelfondertekend certificaat gebruiken

Oplossing: gebruik een openbaar door CA uitgegeven SSL-certificaat voor de webhookcallback-server.

Niet-vertrouwde CA

  • Probleem: de server verzendt het tussenliggende certificaat niet

Oplossing: installeer de tussenliggende certificaten op de webhookcallback-server.

Zie https://www.digicert.com/kb/ssl-certificate-installation.htm voor meer informatie.

Ontbrekende tussencertificaten

Verificatie van clientcertificaten

Om een tweerichtings-SSL in te stellen voor een webhook vragen we de beheerder een p12- (of pfx)-bestand met de privésleutel te uploaden. Het bestand wordt veilig opgeslagen in het klantaccount en de beheerder heeft volledige controle om het op elk moment te verwijderen.

In een tweerichtingswebhookconfiguratie is Acrobat Sign de beller/client en heeft de privésleutel nodig om te bewijzen dat de aanroep is gedaan door Acrobat Sign namens de klantaccount.

  1. Controleren of SSL in twee richtingen is ingeschakeld

    SSL in twee richtingen moet zijn ingeschakeld op de webhookcallback-server.

    Maak via elke webbrowser verbinding met de webhookcallback-URL. U zou het volgende moeten krijgen:

    400 Bad Request
Geen vereist SSL-certificaat verzonden

    Dit betekent dat de server verwacht dat de client clientcertificaten verzendt (d.w.z.: tweerichtings-SSL is ingeschakeld voor de server).

    Als het bovenstaande bericht niet wordt weergegeven, is tweerichtings-SSL niet ingeschakeld.

    Opmerking:

    U kunt Postman gebruiken en een POST-verzoek doen naar de webhookcallback-URL. U zou een vergelijkbaar resultaat moeten krijgen.

  2. Clientcertificaat lokaal verifiëren

    De aanmeldingsgegevens van de klant kunnen een zelfondertekend certificaat of een door CA uitgegeven certificaat zijn. Ze moeten echter minimaal voldoen aan de volgende X.509 v3-uitbreidingen:

    X.509 v3-uitbreiding

    Waarde

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    Het clientcertificaat moet een PKCS12-bestand zijn met de extensie .p12 of .pfx, en het moet zowel het clientcertificaat bevatten (zodat de server de identiteit van de client kan verifiëren) als de persoonlijke sleutel van de client ( zodat de client berichten digitaal kan ondertekenen voor de server om te verifiëren tijdens de SSL-handshake). 

    Gebruik de opdracht openssl om het p12- (pfx)-bestand te verifiëren:

    openssl pkcs12 -info -in outfile.p12

    De wachtwoordzin voor de privésleutel moet worden aangevraagd. De uitvoer moet zowel certificaten als een versleutelde privésleutel bevatten, zoals:

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

    De certificaten moeten ten minste het certificaat van de eindentiteit en de tussentijdse certificaten bevatten. Idealiter bevat het ook het CA-rootcertificaat.  

    Zorg ervoor dat het p12- of pfx-bestand beveiligd is met een wachtwoordzin.

  3. Een zelfondertekend clientcertificaat maken (optioneel)

    Clientcertificaten kunnen door een CA worden uitgegeven of zelfondertekend zijn, afhankelijk van uw wensen.

    Gebruik de opdracht openssl om een zelfondertekend clientcertificaat te genereren:

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

    Let op:

    Houd de resulterende bestanden geheim, aangezien dit uw zelfondertekende CA-certificaten zijn.

    Genereer vervolgens het p12-klantbestand:

    1. Een privésleutel genereren voor de SSL-klant:

      openssl genrsa -out client.key 2048

    2. Gebruik de privésleutel van de klant om een certificatieverzoek te genereren:

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

    3. Het klantcertificaat uitgeven met behulp van het certificeringsverzoek en het CA-certificaat/sleutel:

      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. Converteer het klantcertificaat en de privésleutel naar pkcs#12-indeling voor gebruik door browsers:

      openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12

    5. Verwijder de persoonlijke sleutel van de klant, het klantcertificaat en de klantaanvraagbestanden, aangezien de pkcs12 alles heeft wat u nodig hebt.

      rm client.key client.cer client.req

  4. Het klantcertificaat controleren ten opzichte van de externe server

    • Gebruik Postman om het PFX-bestand van de klant te laden in Instellingen > Certificaten.
    • Selecteer Certificaat toevoegen om het klantcertificaat toe te voegen.
    Instellingen Postman

    • Configureer de HTTP-header voor x-adobesign-clientid:
    De koptekst configureren

    Eenmaal geconfigureerd stuurt u een POST-verzoek naar de webhook callback-URL.

    U zou een 200-reactie moeten krijgen.

  5. Waarom weigert Acrobat Sign mijn PFX-bestand, zelfs nadat ik het met Postman heb geverifieerd?

    Als u het bovenstaande proces voor pfx-bestandsverificatie hebt gevolgd en Acrobat Sign het pfx-bestand nog steeds weigert, dan is het bestand waarschijnlijk gegenereerd door een Microsoft-tool die een niet-standaard PKCS12-bestand kan produceren.

    Gebruik in dat geval de onderstaande openssl-opdrachten om de certificaten en de persoonlijke sleutel uit het pfx-bestand te extraheren en genereer vervolgens een PKCS12-bestand met de juiste indeling:

    // Certificaten en privésleutel extraheren uit pfx-bestand
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

// Nieuw PKCS12-bestand maken
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx


In- of uitschakelen

Toegang tot de webhookfunctie is standaard ingeschakeld voor accounts op ondernemingsniveau.

Beheerders op groepniveau kunnen webhooks maken/controleren die alleen binnen de groep functioneren.

Als u de pagina Webhooks wilt openen, gaat u naar de linkerkant van het menu Beheer: Account > Webhooks


Een webhook activeren

Wanneer een webhook voor de eerste keer wordt gemaakt, is de status voor de webhook Actief.

Op de pagina Webhooks in Acrobat Sign worden standaard de actieve webhooks getoond.

Een niet-actieve webhook activeren:

  • Klik op het pictogram Opties (drie horizontale lijnen) rechts van de webhookkoptekstrij en selecteer Alle webhooks weergeven

 

  • Klik één keer op de inactieve webhook om deze te selecteren
    • De opties voor de webhook worden onder de koptekstrij getoond
  • Klik op Activeren

Zodra de volgende gebeurtenis wordt geactiveerd, start de actieve webhook begint met het verzenden van gegevens naar de doel-URL.


Een webhook uitschakelen

Om een webhook uit te schakelen, hoeft u alleen maar de volgende stappen uit te voeren

  • Navigeer naar de pagina Webhooks
  • Klik één keer op de webhook die u wilt deactiveren
  • Selecteer Deactiveren in de menuopties onder de koprij
    • Wanneer een webhook is uitgeschakeld, is zijn status Niet actief


Een webhook weergeven of bewerken

U kunt webhooks altijd bewerken en opslaan, en als u een nieuwe configuratie opslaat, is de wijziging direct van kracht.

Alleen Gebeurtenissen en Meldingsparameters kunnen worden bewerkt.

Als u Naam, Bereik of URL wilt wijzigen, moet u een nieuwe webhook maken.

De parameters van een webhook bewerken:

  • Navigeer naar de pagina Webhooks 
  • Klik één keer op de webhook die u wilt bewerken
  • Klik op de optie Weergeven/Bewerken onder de koptekstrij

 

  • Voer de benodigde wijzigingen door en klik op Opslaan


Een webhook verwijderen

Een webhook kan altijd worden verwijderd.

Als u een webhook verwijdert, wordt deze in het systeem vernietigd. U kunt een verwijderde webhook dus niet herstellen of terugzetten.

Webhooks hoeven niet eerst te worden gedeactiveerd.

Een webhook verwijderen:

  • Navigeer naar Webhooks
  • Klik één keer op de webhook die u wilt verwijderen
  • Klik op de optie Verwijderen onder de koptekstrij
  • U wordt gevraagd of u zeker weet dat u de webhook wilt verwijderen. Klik op OK


Best practices

  • Bestand tegen duplicatie - Als u één en dezelfde webhook-URL deelt met meerdere apps, en als dezelfde gebruiker is toegewezen aan elke app, wordt dezelfde gebeurtenis meerdere keren naar uw webhook verzonden (één keer per app). In sommige gevallen kan uw webhook dubbele gebeurtenissen ontvangen. Uw webhooktoepassing moet hiermee kunnen omgaan en dedupliceren op gebeurtenis-ID.
  • Atijd snel reageren op webhooks - Uw app heeft maar een paar seconden om op webhookverzoeken te reageren. Voor het verzoek om besturing is dit slechts zelden een probleem, zoals uw app hoeft geen real uitvoeren reageren. Bij meldingsverzoeken doet de app meestal iets dat tijd kost als reactie op het verzoek. 

Als u bijvoorbeeld dan ondertekende documenten verwerken en moet opslaan. Om ervoor te zorgen, kunt u altijd binnen tien seconden reageren, moet u uw werk op een aparte verbinding altijd doen of asynchroon een wachtrij gebruiken.

  • Gelijktijdigheid beheren - Wanneer een gebruiker snel achter elkaar een aantal veranderingen aanbrengt, ontvangt uw app waarschijnlijk meerdere meldingen voor dezelfde gebruiker op ongeveer hetzelfde tijdstip. Als u niet voorzichtig bent met het beheer van gelijktijdigheid, is het mogelijk dat de app dezelfde wijzigingen voor dezelfe gebruiker meermalen aanbrengt. 
  • Om te profiteren van Acrobat Sign-webhooks moet u een duidelijk begrip hebben van het gebruik van de informatie. Stel uzelf de volgende vragen: 

1. Welke gegevens wilt u retourneren in de payload? 

2. Wie heeft toegang tot deze informatie? 

3. Welke beslissing of rapport wordt hierdoor gegenereerd?

  • Aanbevelingen voor het ontvangen van een ondertekend document - Er zijn verschillende factoren waarmee u rekening moet houden bij het bepalen hoe u een ondertekende PDF van Acrobat Sign in uw documentbeheersysteem ontvangt. 

Hoewel het volkomen acceptabel is om gewoon de optie Overeenkomst van ondertekend document te selecteren tijdens het maken van een webhook, kunt u overwegen de Acrobat Sign-API te gebruiken om de documenten op te halen wanneer een activerende gebeurtenis (zoals de overeenkomststatus Voltooid) is ontvangen.


Dingen om rekening mee te houden...

Beperking van JSON-grootte

De grootte van de JSON-lading is beperkt tot 10 MB.

Als een gebeurtenis een grotere payload genereert, wordt een webhook geactiveerd, maar de attributen van voorwaardelijke parameters, als die aanwezig zijn in het verzoek, worden verwijderd om de payload te verkleinen. 

"ConditionalParametersTrimmed " wordt in de respons geretourneerd wanneer de client hierdoor wordt geïnformeerd dat de conditionalParameters -informatie is verwijderd.

“conditionalParametersTrimmed” is een array-object met informatie over de sleutels die zijn afgekapt.

De afkapping vindt plaats in de onderstaande volgorde:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

De ondertekende documenten worden eerst worden afgekapt, gevolgd door deelnemerinformatie op, documentgegevens en de uiteindelijke gedetailleerde informatie.

Dit kan bijvoorbeeld op een gebeurtenis ook gebeuren als het agreement ondertekend document (versleutelde grondtal 64) of voor een agreement met meerdere formuliervelden bevat


Webhook-meldingen

Acrobat Sign-webhooks leveren meldingen die van toepassing zijn op alle deelnemers aan een overeenkomst als er een webhook is geconfigureerd voor die gebruiker, hun groep of hun account.

Overeenkomstgebeurtenissen worden zo verwerkt dat als er een webhook is geconfigureerd voor de betreffende deelnemer van die gebeurtenis, er een melding naar die webhook-URL wordt verzonden. Met andere woorden, webhooks worden geactiveerd voor gebeurtenissen in alle toepasselijke overeenkomsten, zelfs die buiten de groep of account waarin de webhook is geconfigureerd.

Meldingen worden alleen geleverd voor die gebeurtenissen waarbij de deelnemer betrokken is. De afzender van een overeenkomst ontvangt bijvoorbeeld bijna elke melding, terwijl ontvangers alleen meldingen ontvangen vanaf het begin van hun betrokkenheid bij de overeenkomst, en alleen voor die evenementen waarin ze betrokken zijn.

Webhookmeldingen volgen het huidige verificatie- en zichtbaarheidsmodel van Acrobat Sign zelf, wat betekent dat gebruikers pas toegang hebben tot de overeenkomst wanneer de deelname van de gebruiker aan een overeenkomst is begonnen.

De afzender stuurt een overeenkomst ter ondertekening naar drie ondertekenaars.

  • Er is een accountniveau WebhookX geconfigureerd voor het account van de afzender.
  • Signer1 is lid van hetzelfde account als de afzender maar in een andere groep en er is een WehbhookY geconfigureerd voor die groep.
  • Signer2 is lid van een ander account en er is een accountniveau WebhookZ geconfigureerd voor het Signer2-account.
  • Signer3 is lid van hetzelfde account als een afzender.

De Afzender stuurt een overeenkomst: WebhookX activeert Overeenkomst gemaakt en Overeenkomst verzonden terwijl WebhookY Overeenkomst verzonden activeert.

Signer1 ondertekent: WebhookX activeert Overeenkomst deelnemer voltooid en Overeenkomst verzonden, WebhookY activeert Overeenkomst deelnemer voltooid en WebhookZ activeert Overeenkomst verzonden.

Signer2 ondertekent: WebhookX activeert Overeenkomst deelnemer voltooid en Overeenkomst verzonden, terwijl WebhookZ een melding verzendt voor Overeenkomst deelnemer voltooid.

Signer3 ondertekent: WebhookX activeert Overeenkomst deelnemer voltooid en Overeenkomst workflow voltooid, WebhookY activeert Overeenkomst workflow voltooid en WebhookZ activeert Overeenkomst workflow voltooid.


Probeer het opnieuw wanneer de listening-service niet beschikbaar is

Als de doel-URL voor de webhook om welke reden dan ook niet beschikbaar is, zal Acrobat Sign de JSON in de wachtrij plaatsen en de push opnieuw proberen in een progressieve cyclus van 72 uur.

De niet-afgeleverde gebeurtenissen worden bewaard in een wachtrij voor opnieuw proberen en er wordt de komende 72 uur alles aan gedaan om de meldingen af te leveren in de volgorde waarin ze zijn opgetreden.

De strategie voor het opnieuw proberen van de levering van meldingen is een verdubbeling van de tijd tussen pogingen, beginnend met een interval van 1 minuut oplopend tot elke 12 uur, wat resulteert in 15 nieuwe pogingen in een tijdsbestek van 72 uur.

Als de webhookontvanger niet binnen 72 uur reageert en er in de afgelopen zeven dagen geen succesvolle leveringen van meldingen zijn geweest, wordt de webhook uitgeschakeld. Geen meldingen worden naar dit URL opnieuw verzonden tot webhook wordt geactiveerd.

Alle meldingen webhook tussen het moment is uitgeschakeld en het later opnieuw ingeschakeld, zullen verloren gaan.

Adobe-logo

Aanmelden bij je account

Snelle koppelingen

Al je lidmaatschappen weergeven Je lidmaatschappen beheren

Juridische kennisgevingen    |    Online privacybeleid