Konfigurer webhooks

Søg

Oversigt

En webhook er en brugerdefineret HTTPS-anmodning, der udløses, når en bestemt hændelse opstår på kildewebstedet (Adobe Acrobat Sign i dette tilfælde).

En webhook er derfor blot en REST-tjeneste, der accepterer data eller en strøm af data.

Webhooks er beregnet til tjeneste-til-tjeneste-kommunikation i en PUSH-model.

Når der opstår en abonneret hændelse, skaber Acrobat Sign en HTTPS POST med JSON-brødtekst og leverer det til den angivne URL-adresse.

 

Webhooks har flere fordele i forhold til den tidligere callback-metode, hvoraf nogle er:

  • Administratorer kan aktivere deres egne webhooks uden at skulle involvere Acrobat Sign-support til at vise tilbagekald-URL'en
  • Webhooks er bedre i forhold til datas "friskhed", kommunikationseffektivitet og sikkerhed. Ingen meningsmåling påkrævet
  • Webhooks giver nemt mulighed for forskellige niveauer af omfang (Konto/Gruppe/Bruger/Ressource). 
  • Webhooks er en mere moderne API-løsning, der giver mulighed for nemmere konfiguration af moderne programmer
  • Flere webhooks kan konfigureres pr. omfang (Konto/Gruppe/Bruger/Ressource), hvor tilbagekald skulle være unikke
  • Webhooks giver mulighed for at vælge de data, der skal returneres, hvor tilbagekald er en "alt eller intet"-løsning
  • Metadata, der bæres med en webhook, kan konfigureres (grundlæggende eller detaljeret)
  • Webhooks er langt nemmere at oprette, redigere eller deaktivere efter behov, da brugergrænsefladen er helt inden for administratorkontrol.
Bemærk:

Dette dokument er primært fokuseret på Webhooks-brugergrænseflade i webprogrammet Acrobat Sign (Tidligere Adobe Sign).

Udviklere, der leder efter API-oplysninger, kan finde flere oplysninger her:

Sådan bruges det

Administratorer skal først have en webhook-tjeneste, der er klar til at acceptere det indgående push fra Acrobat Sign. Der er mange muligheder i denne henseende, og så længe tjenesten kan acceptere POST- og GET-anmodninger, vil webhook være vellykket.

Når tjenesten er klar, kan en Acrobat Sign-administrator oprette en ny webhook fra Webhook-grænsefladen i Konto-menuen på Acrobat Sign-webstedet.

Administratorer kan konfigurere webhooken til at udløses for hændelserne Aftale, Webformular (widget) eller Send i massevis (MegaSign). Biblioteksskabelon-ressourcen (biblioteksdokument) kan også konfigureres via API'en.

Omfanget af webhooken kan være hele kontoen eller individuelle grupper via administratorgrænsefladen. API'en giver mulighed for mere finkornethed gennem valg af BRUGER- eller RESSOURCE-omfang.

Den type data, der skubbes til webadressen, kan konfigureres og kan omfatte ting som aftaleoplysninger, deltageroplysninger, dokumentoplysninger og så videre.

Når webhooken er konfigureret og gemt, vil Acrobat Sign skubbe et nyt JSON-objekt til den definerede URL, hver gang udløserhændelsen udløses. Ingen løbende manipulation af webhook er påkrævet, medmindre du ønsker at ændre begivenhedens udløserkriterier eller JSON nyttelast.

Godkendelse af hensigten med webhook-URL'en

Før en webhook registreres, kontrollerer Acrobat Sign, om den webhook-URL, der er angivet i registreringsanmodningen, vil modtage notifikationer eller ej. Når Acrobat Sign modtager en ny webhook-registreringsanmodning, foretages der til dette formål først en verifikationsanmodning til webhook-URL'en. Denne bekræftelsesanmodning er en HTTPS GET-anmodning sendt til webhook-URL'en. Denne anmodning har et brugerdefineret HTTP header X-AdobeSign-ClientId. Værdien i denne overskrift er indstillet til klient-id (Application ID) for API-programmet, der anmoder om at oprette/registrere webhooken. For at kunne registrere en webhook skal webhook-URL'en svare på denne verifikationsanmodning med en 2XX-svarkode, OG ydermere SKAL den sende samme klient-id-værdi tilbage på én af følgende to måder:

  • I en svaroverskrift X-AdobeSign-ClientId. Det er samme overskrift, der sendes i anmodningen og gentages i svaret.
  • Eller i JSON-svarets brødtekst, hvor nøglen til xAdobeSignClientId og dens værdi er samme klient-id, der sendes i anmodningen.

Webhooken vil kun blive registreret på et svar(2XX svarkode) og validering af klient-id enten i overskrift eller svartekst. Formålet med denne bekræftelsesanmodning er at vise, at din webhook-URL virkelig ønsker at modtage notifikationer på den pågældende URL. Hvis du ved et uheld indtastede den forkerte URL, svarer URL'en ikke korrekt på bekræftelsen af hensigten, og Acrobat Sign sender ingen notifikationer til den URL. Derudover kan webhook-URL'en også validere, at den kun vil modtage notifikationer via de webhooks, der er registreret af et bestemt program. Det kan gøres ved at validere klient-id'et for programmet, der blev sendt i X-AdobeSign-ClientId-overskriften. Hvis webhook-URL'en ikke genkender klient-id'et, MÅ DEN IKKE svare med succesresponskoden, og Acrobat Sign vil sørge for, at URL-adressen ikke registreres som en webhook.

Bekræftelsen af webhook URL-opkald vil blive foretaget i følgende scenarier:

  • Registrering af webhook: Hvis denne bekræftelse af webhook URL-opkaldet mislykkes, vil webhooken ikke blive oprettet.
  • Opdaterer Webhook: INAKTIV til AKTIV: Hvis denne bekræftelse af webhook URL-opkaldet mislykkes, vil webhook-tilstanden ikke blive ændret til AKTIV.

Sådan reagerer du på en webhook-notifikation

Acrobat Sign udfører en implicit verificering af hensigten i hver enkelt webhook-notifikationsanmodning, der sendes til webhook-URL'en. Således indeholder hver enkelt webhook-meddelelse HTTPS-anmodning også den brugerdefinerede HTTP-header kaldet X-AdobeSign-ClientId. Værdien af denne overskrift er klient-id (Application ID) for det program, der oprettede webhook. Vi anser webhook-notifikationen for at være leveret med succes, hvis, og kun hvis, et svar om succes (2XX-svarkode) returneres, og klient-id sendes i enten HTTP-sidehovedet (X-AdobeSign-ClientId) eller i en JSON-svartekst med nøgle som xAdobeSignClientId og værdi som det samme klient-id, ellers forsøger vi igen at levere notifikationen til webhook-URL, indtil forsøgene er opbrugt.

Som nævnt ovenfor er overskriften 'X-AdobeSign-ClientId', som er inkluderet i hver enkelt anmodning om meddelelse fra Sign, værdien af denne overskrift(klient-id)  bør ekko tilbage som svar på en af to måder:

1. HTTP-overskrift X-AdobeSign-ClientId og værdi som denne klient-id

Eksempel Javascript-kode til at hente klient-id, validere det, og derefter returnere det i svaroverskrift

// Hent klient-id

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

 

//Valider det

if (clientid ==="BGBQIIE7H253K6") // Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

{

    //Return it in response header

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

    response.status = 200;  // default value

}

Eksempel på PHP-kode til at hente klient-id, validere det, og derefter returnere det i svaroverskriften

<?php

// Hent klient-id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valider det

if($clientid == "BGBQIIE7H253K6") //Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

{

    //Return it in response header

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

   header("HTTP/1.1 200 OK"); // default value

}

?>


2. JSON-svartekst med nøgle som xAdobeSignClientId og værdi som samme klient-id

Eksempel på Javascript-kode til at hente klient-id, validere den og returnere den i svarteksten

// Hent klient-id

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

 

 

//Valider det

if (clientid ==="BGBQIIE7H253K6") // Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Return Client Id in the body

                       };

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

    response.body = responseBody;

    response.status = 200;

}

Eksempel på PHP-kode til at hente klient-id, validere den, og returnere den i svarteksten

<?php

// Hent klient-id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valider det

if($clientid == "BGBQIIE7H253K6") //Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

{

   //Return it in response body

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

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

   echo json_encode($body);

   header("HTTP/1.1 200 OK"); // default value

}

?>

Eksempel på JSON-svarteksten

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Forudsætninger

Du skal have:

  1. En Microsoft-konto med licens til at oprette Azure Functions-programmer
  2. Du kan oprette et eksisterende Azur Function-program via https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function 
  3. Grundlæggende kendskab til Javascript, så du kan forstå og skrive koden på et hvilket som helst sprog efter eget valg

Skridt til at oprette en Azure Functions-udløser, der fungerer som en Acrobat Sign-webhook

Sådan opretter du en Javascript HTTP-udløserfunktion:

1. Log ind via din Microsoft-konto https://portal.azure.com/

2. Åbn dit Azure Function-program, som vises under fanen Function-programmer.

Dette vil åbne din liste over Azure Function-programmer:

3. Vælg det program, hvor du vil oprette denne nye funktion

4. Klik på knappen Opret (+) for at oprette en ny Azure-funktion

 

5. Vælg Webhook + API som scenarie og Javascript som sprog

6. Klik på Opret denne funktion

Der oprettes en ny funktion, der har kan håndtere en indgående API-anmodning.

Tilføj logik for registrere Acrobat Sign-webhook

Før en webhook er registreret, bekræfter Acrobat Sign, at den webhook URL, der er angivet i registreringsanmodningen, virkelig har til hensigt at modtage meddelelser eller ej. Når en ny webhook registreringsanmodning modtages af Acrobat Sign til dette formål, foretager den først en verificeringsanmodning til webhook-URL'en. Denne verificeringsanmodning er en HTTPS GET-anmodning, som er sendt til webhook-URL'en med en brugerdefineret HTTP-overskrift X-AdobeSign-ClientId. Værdien i denne overskrift er indstillet til klient-id for det program, der anmoder om at oprette/registrere webhook. For at kunne registrere en webhook reagerer webhook-URL'en på denne verifikationsanmodning med en 2XX-svarkode, OG den kan desuden sende den samme klient-id-værdi tilbage på én af følgende to måder.

Der er to muligheder, du kan følge:


Valgmulighed 1: Klient-id i X-AdobeSign-ClientId som svaroverskrift

Send X-AdobeSign-ClientId i svaroverskriften. Det er den samme overskrift, der sendes i anmodningen og gentages i svaret.

Erstat Index.js-filen med følgende kodestykke:

module.exports = function (context, req) {

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

    // Validate that the incoming ClientID is genuine

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: "Notification Accepted",

            headers : {

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

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Test adfærden ved at trods anmodningen:

1. Klik på knappen Test i øverste højre hjørne

2. Trods anmodningen om dummy

Selvom svaroverskrifter ikke er vist ovenfor, kan du stadig observere det ved at trodse det ved hjælp af postbud/DHC eller en anden tjeneste.


Mulighed 2: Klient-id i svarbrødteksten med nøglen xAdobeSignClientId

I JSON-svarets brødtekst, hvor nøglen til xAdobeSignClientId og dens værdi er det samme klient-id, der sendes i anmodningen.

Erstat Index.js-filen med følgende kodestykke:

module.exports = function (context, req) {

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

    // Validate that the incoming ClientID is genuine

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Test adfærden ved at trodse anmodningen

1. Klik på knappen Test i øverste højre hjørne

2. Trods anmodningen om dummy

Bemærk også, at den samme adfærd for client-id forventes, når webhook-URL modtager POST-notifikationer. 


Klar til brug

Når du har verificeret adfærden, fungerer webhook-URL'en i henhold til Acrobat Sign-standarderne. Du kan yderligere opdatere den brugerdefinerede logik i henhold til dine krav.

 

Hent funktions-URL

  • Klik på Hent funktions-URL

 

Kopiér URL'en, og brug den til at oprette webhooks i Acrobat Sign.

Oprettelse af AWS Lambda-funktionen

For at oprette en AWS Lambda-funktion skal du logge ind på din AWS Management Console og vælge AWS Lambda-tjenesten fra listen over tjenester.

  • Klik på indstillingen Opret en Lambda-funktion vha. "Forfatter fra bunden"
  • På siden Konfigurer funktion indtaster du funktionsnavnet "lambdaWebhooks" og vælger Node.js 4.3 som Runtime
  • For Rollen, skal du vælge en eksisterende rolle, eller oprette en ny rolle fra skabelon(er)
    • Hvis du har valgt  Opret ny rolle fra skabelon(er), skal du indtaste et rollenavn (f.eks. rollelamda) og vælge Simple Microservices-tilladelser fra listen Poiliti-skabeloner
  • Klik på knappen Opret funktion

  • På den nye AWS lamda funktionsside skal du vælge "Rediger kode i linje" som "Kodeindstastningstype" og beholde index.handler som Handler.
  • Tilføj logik for at registrere Acrobat  Sign Webhook

    Før en webhook er registreret, bekræfter Acrobat Sign, at den webhook URL, der er angivet i registreringsanmodningen, virkelig har til hensigt at modtage meddelelser eller ej. Når en ny webhook registreringsanmodning modtages af Acrobat Sign til dette formål, foretager den først en verificeringsanmodning til webhook-URL'en. Denne verificeringsanmodning er en HTTPS GET-anmodning, som er sendt til webhook-URL'en med en brugerdefineret HTTP-overskrift X-AdobeSign-ClientId. Værdien i denne overskrift er indstillet til klient-id for det program, der anmoder om at oprette/registrere webhook. For at kunne registrere en webhook reagerer webhook-URL'en på denne verifikationsanmodning med en 2XX-svarkode, OG den kan desuden sende den samme klient-id-værdi tilbage på én af følgende to måder. Bemærk også, at den samme adfærd for client-id forventes, når webhook-URL modtager POST-notifikationer. 

    Følg et af de to tilfælde:

    Tilfælde 1: Send Client-Id i X-AdobeSign-ClientId som svaroverskrift

    •  Send X-AdobeSign-ClientId i svaroverskriften. Det er den samme overskrift, der sendes i anmodningen og gentages i svaret.

      Kodestykke
      I index.js-filen skal du erstatte den automatisk genererede kodestykke med følgende kode:

Prøveknude JS-kode til at hente klient-id, validere det, og derefter returnere det i svaroverskrift

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

  // Hent klient-id

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

 

  //Valider det

  if (clientid =="BGBQIIE7H253K6") // Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! illegitimate call");

  }

}

 

Case 2: Klient-id i svarlegemet med nøgle xAdobeSignClientId

I JSON-svarets brødtekst, hvor nøglen til xAdobeSignClientId og dens værdi er det samme klient-id, der sendes i anmodningen.

 

Kodestykke

Erstat Index.js-filen med følgende kodestykke:

Prøveknude JS-kode til at hente klient-id, validere det, og derefter returnere det i svaroverskrift

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

 // Hent klient-id

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

  

 //Valider det

 if (clientid =="BGBQIIE7H253K6") // Erstat 'BGBQIIE7H253K6' med klient-id'et for det program, hvormed webhook'en er oprettet

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Opps!! illegitimate call");

  }

}

  • Gem funktionen. Lambda-funktionen er skabt, og vi er næsten klar til at bruge den i en webhook i realtid.

 

Konfiguration af AWS API Gateway

For at gøre denne Lambda offentligt tilgængelig via en HTTP-metode skal vi konfigurere AWS API Gateway ved hjælp af vores funktion(oprettet ovenfor) som backend for API'en.

Vælg API-gatewayen fra AWS-tjenesterne i AWS Management Console, og klik på knappen Opret API

  • Vælg Ny API på siden Opret ny API, og indtast webhooks som API-navn.
  • Klik på knappen Opret API
  • Vælg rullelisten Handlinger, og vælg indstillingen Opret ressource
  • Markér muligheden Konfigurer som en proxyressource, og angiv valider som Ressourcenanv og {proxy+} i Ressourcesti
  • Lad indstillingen Aktiver API Gateway CORS være umarkeret, og klik på knappen Opret ressource
  • Hold Lambda Function Proxy valgt som Integrationstype, og vælg det område, hvor du har oprettet din Lambda-funktion i rullelisten Lambda-region (sandsynligvis er det det samme område, hvor du opretter API Gateway).
  • Indtast valider som Lambda-funktionen og klik på knappen Gem
  • I pop op-vinduet Tilføj tilladelse til Lambda-funktion skal du vælge OK

Hvis alle ovenstående trin udføres korrekt, ser du noget som dette:

Implementering af API

Det næste skridt er at implementere denne API, så den bliver klar til brug.

  • I rullemenuen Handlinger skal du vælge Implementer API
  • Vælg [Ny fase] i implementeringsfasen, og indtast prod (eller noget, du gerne vil identificere denne fase) i fase-navnet
  • Klik på knappen Udrul

API er nu klar til brug, og du kan finde den finde URL i den blå boks, som vises herunder:

Bemærk denne webadresse, da du skal angive den som din webadresse til webhook i realtid.

Klar til brug

Det er gjort. Brug url'en ovenfor med "/{nodeJSfunctionName}"POST /webhooks API-anmodning.  Når du har verificeret adfærden, er webhook-URL'en funktionel i henhold til
Acrobat Sign-standarder. Du kan yderligere opdatere/tilføje den brugerdefinerede logik i henhold til dit krav.

Konfigurationsindstillinger

Konfiguration af webhook kræver, at der defineres fem elementer:

  • Navn – det foreslås at oprette et intuitivt navn, som andre administratorer nemt kan forstå.
  • Omfang – hvor bredt er det net, som webhooken fanger? Konto og Gruppe er tilgængelige i grænsefladen.
    • API'en understøtter omfangene Konto, Gruppe, Bruger og Ressource.
    • Der kan kun defineres ét omfang per webhook.
  • URL – den mål-URL, som Acrobat Sign skubbede JSON-nyttedataene til.
  • Hændelser – den udløser, der får Acrobat Sign til at oprette JSON og skubbe den til URL'en.
    • Hver enkelt hændelse opbygger en anden nyttedata, der er relevant for udløserhændelsen.
    • Flere hændelser kan inkluderes i én webhook.
  • Notifikationsparametre – notifikationsparametrene identificerer afsnittene i JSON-nyttedataene til hændelsen, så du kun kan vælge de afsnit i hændelsen, der er vigtige for denne webhook (og dermed reducere unødvendige data sendt til din URL).

Når webhook er fuldt defineret, skal du klikke på Gem, hvorefter den nye webhook begynder at reagere for at udløse hændelser med det samme. 

Bemærk:

Konfigurer din webhook-URL til at svare på webhook-bekræftelsen og webhooknotifikationsanmodningerne i henhold til den bekræftelsesprotokoll, som forklares ovenfor. Det klient-id (Program-id), der sendes til webhooks, som oprettet fra webprogrammet Acrobat Sign, er - UB7E5BXCXY

Konfigurer webhook



Omfang

  • Konto: Alle de abonnerede hændelser, der forekommer på kontoen, udløser skubbet.
    • Kontoadministratorer har tilladelse til at se alle webhooks, der er defineret for kontoen, og alle grupper inden for den pågældende konto.
  • Gruppe: Alle de abonnerede hændelser, der forekommer i denne gruppe, udløser skubbet. BEMÆRK: Gruppebaserede webhooks findes kun for den ene gruppe.
    • Gruppeadministratorer vil kun se de webhooks, der er dedikeret til deres gruppe. De kan ikke se webhooks på kontoniveau eller webhooks, der er bundet til andre grupper.
    • Konti, der har Brugere i flere grupper aktiveret, vil se muligheden for at indstille gruppen, som omfanget skal anvendes på.
  • Brugerkonto: Alle tilmeldte begivenheder for en brugerkonto udløser push. Webhooks på brugerniveau kan kun oprettes via API.
  • Webhook på ressourceniveau: Dette vil blive oprettet for en bestemt ressource. Begivenheder, der er specifikke for denne ressource, vil blive skubbet til webhook-URL'en. Webhooks på ressourceniveau kan kun oprettes via API.

URL

En webhook-URL er en server, der lytter efter indgående HTTPS POST-meddelelser, der udløses, når begivenheder opstår.

Du skal bruge denne URL for at abonnere på dit webhook til begivenheder.

  • Klienten skal indeholde en HTTPS-URL, som Acrobat Sign kan POST til. Denne URL skal være tilgængelig på det offentlige internet.  
    • For eksempel fungerer 127.0.0.1 og localhost-URI'er ikke.
    • URL-slutpunktet skal lytte på port 443 eller 8443 (bestemmes af kunden, når tilbagekaldelses-URL'en defineres).
  • Sørg for, at webhook understøtter POST-anmodninger om indgående begivenhedsmeddelelser, og GET anmodninger om bekræftelsesanmodningen.
  • URL'en må ikke blokeres af en firewall.


Hændelser

Nedenfor er de hændelser, der kan udløse et skub til webhook-URL'en, grupperet efter objekt og anført i den rækkefølge, der findes i brugergrænsefladen.

Værdien til venstre er den værdi, du ser i Acrobat Sign-grænsefladen. Værdien til højre er webhook-navnet i API'en.

Du kan finde alle oplysninger om webhooks og deres nyttedata i Vejledning til Acrobat Sign-udviklere.

Aftaler:

UI-element Webhook-navn
Aftale alle hændelser AGREEMENT_ALL
Aftale oprettet AGREEMENT_CREATED
Aftale sendt AGREEMENT_ACTION_REQUESTED
Aftaledeltager fuldført AGREEMENT_ACTION_COMPLETED
Aftalens workflow fuldført AGREEMENT_WORKFLOW_COMPLETED
Aftale udløbet AGREEMENT_EXPIRED
Aftale slettet AGREEMENT_DOCUMENTS_DELETED
Aftale annulleret AGREEMENT_RECALLED
Aftale afvist AGREEMENT_REJECTED
Aftale delt AGREEMENT_SHARED
Aftale delegeret AGREEMENT_ACTION_DELEGATED
Aftaledeltager udskiftet AGREEMENT_ACTION_REPLACED_SIGNER
Aftale ændret AGREEMENT_MODIFIED
Aftaleændring kvitteret for AGREEMENT_USER_ACK_AGREEMENT_MODIFIED
Aftalemailen vist AGREEMENT_EMAIL_VIEWED
Aftalemail blev ikke sendt AGREEMENT_EMAIL_BOUNCED
Aftaleoprettelse mislykket AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
Aftale synkroniseret efter offlinehændelse AGREEMENT_OFFLINE_SYNC
Aftalen uploadet af afsenderen AGREEMENT_UPLOADED_BY_SENDER
Aftale sat i boks AGREEMENT_VAULTED
Aftaledeltagerens sociale identitet godkendt AGREEMENT_WEB_IDENTITY_AUTHENTICATED
Aftaledeltager KBA-godkendt AGREEMENT_KBA_AUTHENTICATED
Aftalepåmindelse sendt AGREEMENT_REMINDER_SENT
Aftaleunderskriverens navn er ændret af underskriveren AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER
   
Aftale-webhooks er kun tilgængelige via API
NA AGREEMENT_EXPIRATION_UPDATED
NA
 AGREEMENT_READY_TO_NOTARIZE
NA
 AGREEMENT_READY_TO_VAULT

 

Send i massevis:

UI-element Webhook-navn
Send i massevis – alle hændelser MEGASIGN_ALL
Send i massevis – oprettet
 MEGASIGN_CREATED
Send i massevis – delt
 MEGASIGN_SHARED
Send i massevis – tilbagekaldt
 MEGASIGN_RECALLED

 

Webformularer:

UI-element Webhook-navn
Webformular – alle hændelser WIDGET_ALL
Webformular – oprettet
 WIDGET_CREATED
Webformular – aktiveret
 WIDGET_ENABLED
Webformular – deaktiveret
 WIDGET_DISABLED
Webformular – ændret
 WIDGET_MODIFIED
Webformular – delt
 WIDGET_SHARED
Webformular – oprettelse mislykket
 WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

 

Biblioteksskabeloner (kun API):

UI-element Webhook-navn
NA LIBRARY_DOCUMENT_ALL
NA LIBRARY_DOCUMENT_CREATED
NA LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
NA LIBRARY_DOCUMENT_MODIFIED

 

Parametre for notifikationer

Med notifikationsparametre kan du tilpasse JSON-nyttelasten til blot specifikke elementer i begivenheden.

I en Aftaledeltager udskiftet-hændelse vil du f.eks. muligvis kun have aftaleoplysningerne og deltageroplysningerne, idet du udelader dokumentoplysningerne og reducerer den samlede størrelse af JSON, der sendes til din webhook-URL.

 

  • Aftale
    • Aftaleoplysninger – detaljerede aftaleoplysninger baseret på aftalens tilstand på tidspunktet for den udløsende begivenhed.
    • Oplysninger om aftaledokument – inkluderer alle dokumentoplysninger, der genereres som resultat af hændelsen.
    • Oplysninger om aftaledeltager – inkluderer eventuelle deltageroplysninger som resultat af hændelsen.
    • Aftale - underskrevet dokument – leverer den underskrevne PDF-fil. 
      • Gælder for Aftalens workflow afsluttet og Hele aftalen-begivenheder.
  • Send i massevis
    • Send i massevis – detaljerede oplysninger om det Send i massevis-objekt, der udløste hændelsen.
  • Webformular
    • Widget-oplysninger – detaljerede oplysninger om webformularen, der udløste begivenheden.
    • Oplysninger om Widget-dokument – de dokumentoplysninger, der er knyttet til webformularen.
    • Oplysninger om widget-deltager – oplysninger om de definerede deltagere i webformularen.

Tovejs SSL-godkendelse

To-vejs-SSL, ofte kaldet Client-Side SSL eller fælles TLS, er en SSL-tilstand, hvor både serveren og klienten (webbrowseren) præsentere certifikater til at identificere sig.

Kontoadministratorer kan konfigurere et klientcertifikat på siden Sikkerhedsindstillinger.

Acrobat Sign verificerer SSL-certifikaterne, når de leverer nyttelast til webhook-URL'en. Webhooks, der ikke opfylder SSL-certifikatkontrollen, vil ikke levere JSON-belastningen korrekt. 

Brug tovejs-SSL til at godkende klienten (Acrobat Sign) og lyttetjenesten for at sikre, at kun Acrobat  Sign kan nå din webhook-URL. 

Hvis webhooken er oprettet af et partnerprogram, vil webhooken bruge et klientcertifikat (hvis det er tilgængeligt) fra partnerprogrammets konto til at identificere sig, når der sendes webhook-notifikationer.

Nedenfor vises de mest almindelige spørgsmål angående både webserverbekræftelsesprocessen og klientcertificeringsbekræftelsen.

Bekræftelse af webserver

Under registreringen af en webhook bekræfter Acrobat Sign URL'en for webhook-serveren.

Kunder vil ikke kunne registrere webhook, hvis forbindelsen til webhook tilbagekaldelses-URL'en ikke kan fuldføres fra Acrobat Sign.

Nej.

Webhook-tilbagekaldelses-URL'en kan kun være HTTPS på port 443 eller 8443.

Acrobat Sign blokerer udgående HTTPS-trafik til alle andre porte.

En god måde at bekræfte servercertifikatet på er at bruge DigiCert® SSL Installation Diagnostics Tool.

Angiv kun værtsnavnet f.eks.: www.digicert.com

Almindelige problemer omfatter:

  • Problem: Brug af en upålidelig CA eller selvsigneret certifikat

Rettelse: Brug et offentligt CA-udstedt SSL-certifikat til webhook-tilbagekaldelsesserveren.

Stoler ikke på CA

  • Problem: Serveren sender ikke det mellemliggende certifikat

Rettelse: Installer de mellemliggende certifikater på webhook-tilbagekaldelsesserveren.

Se https://www.digicert.com/kb/ssl-certificate-installation.htm for yderligere oplysninger.

Manglende mellemliggende certifikater

Bekræftelse af klientcertifikat

For at oprette en tovejs-SSL til en webhook, kræver vi, at administratoren uploader en .p12 (eller .pfx) fil, der indeholder den private nøgle. Filen gemmes sikkert i kundekontoen, og administratoren har fuld kontrol over at fjerne den når som helst.

I opsætning med en to-vejs-webhook er Acrobat Sign opkalder/klient og skal bruge den private nøgle til at bevise, at opkaldet er foretaget af Acrobat Sign på vegne af leverandørens konto.

  1. Bekræft, at tovejs-SSL er aktiveret

    Tovejs-SSL skal være aktiveret på webhook-tilbagekaldelsesserveren.

    Ved hjælp af en hvilken som helst webbrowser skal du oprette forbindelse til webhook-tilbagekaldelses-URL'en. Du bør få:

    400 Fejl i anmodning
Intet påkrævet SSL-certifikat sendt

    Det betyder, at serveren forventer, at klienten sender klientcertifikater (dvs. at tovejs-SSL er aktiveret for serveren).

    Ser du ikke ovenstående besked, er tovejs-SSL ikke aktiveret.

    Bemærk:

    Du kan bruge Postman og foretage en POST-anmodning til webhook-tilbagekaldelses-URL'en. Det burde resultere i et lignende resultat.

  2. Bekræft klientcertifikat lokalt

    Klientens legitimationsoplysninger kan enten være et selvsigneret certifikat eller et CA-udstedt certifikat. Den skal dog mindst opfylde krav til følgende X.509 v3-udvidelser:

    X.509 v3-udvidelse

    Værdi

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    Klientcertifikatet skal være en PKCS12-fil med filtypen .p12 eller .pfx, og det skal indeholde både klientcertifikatet (så serveren kan verificere klientens identitet) og klientens private nøgle (så klienten digitalt kan underskrive meddelelser, som serveren kan verificere under SSL-håndtryk). 

    Brug kommandoen openssl til at bekræfte filen p12 (pfx):

    openssl pkcs12 -info -in outfile.p12

    Adgangssætningen for den private nøgle skal anmodes. Outputtet skal indeholde både certifikater samt en krypteret privat nøgle som:

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

    Certifikaterne bør mindst omfatte slutenhedscertifikatet og de mellemliggende certifikater. Ideelt set vil den også indeholde root CA-certifikatet.  

    Kontrollér, at .p12- eller .pfx-filen er beskyttet med adgangssætning.

  3. Opret et selvunderskrevet klientcertifikat (valgfrit)

    Klientcertifikater kan enten være CA-udstedt eller selvsigneret, afhængigt af dit behov.

    Brug følgende openssl-kommando til at generere et selvsigneret klientcertifikat:

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

    Forsigtig:

    Hold de resulterende filer hemmelige, da de er dine selvsignerede CA-certifikater.

    Derefter skal du generere klienten .p12 fil:

    1. Generér en privat nøgle til SSL-klienten:

      openssl genrsa -out client.key 2048

    2. Brug klientens private nøgle til at generere en certificeringsanmodning:

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

    3. Udsted klientcertifikatet ved hjælp af certificeringsanmodningen og CA-certifikatet/nøglen:

      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. Konverter klientcertifikatet og den private nøgle til pkcs#12-format til brug af browsere:

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

    5. Fjern klientens private nøgle, klientcertifikat og klientanmodningsfiler, da pkcs12 har alt, hvad du behøver.

      rm client.key client.cer client.req

  4. Bekræft klientcertifikatet mod fjernserveren

    • Brug Postman til at indlæse klientens PFX-fil i Indstillinger > Certifikater.
    • Vælg Tilføj certifikat for at tilføje klientcertifikatet.
    Indstillinger for Postman

    • Konfigurer HTTP-sidehovedet for x-adobesign-clientid:
    Konfigurer sidehoved

    Når det er konfigureret, skal du sende en postanmodning til webhook callback URL.

    Du burde få et svar på 200.

  5. Hvorfor afviser Acrobat Sign min PFX-fil, selv efter at jeg har verificeret den med Postman?

    Hvis du har fulgt ovenstående proces for pfx-filverifikation, og Acrobat Sign stadig afviser pfx-filen, er det sandsynligt, at filen blev genereret af et Microsoft-værktøj, der kan producere en ikke-standard PKCS12 fil.

    I så fald skal du bruge nedenstående openssl-kommandoer til at udtrække certifikaterne og den private nøgle fra pfx-filen og derefter generere en korrekt formateret PKCS12-fil:

    // Udtræk certifikater og privat nøgle fra pfx-fil
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

// Opret ny PKCS12-fil
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx

Aktivering og deaktivering

Adgang til funktionen Webhooks er som standard aktiveret for virksomhedsplankonti.

Administratorer på gruppeniveau kan oprette/styre de webhooks, der kun opererer inden for deres gruppe.

Adgang til Webhooks-siden kan findes i venstre skinne i Admin-menuen: Konto > Webhooks

Aktivér en webhook

Når en webhook først oprettes, oprettes den i en Aktiv-status.

På Webhooks-siden i Acrobat Sign kan du som standard se de aktive webhooks.

Sådan aktiverer du en inaktiv webhook:

  • Klik på ikonet Indstillinger (tre vandrette linjer) til højre for webhooks-overskriftsrækken, og vælg Vis alle webhooks

 

  • Klik én gang på aftalen for at vælge den
    • Dette viser indstillingerne for webhook lige under overskriftsrækken
  • Klik på Aktivér

Den aktive webhook vil begynde at sende data til URL-adressen, så snart den næste begivenhed udløses.

Deaktiver en webhook

Deaktivering af en webhook kræver kun, at du

  • Gå til siden Webhooks
  • Klik én gang på den webhook, du vil deaktivere
  • Vælg Deaktiver fra menupunkterne under overskriftsrækken
    • Når den er deaktiveret, viser webhooken en status for Inaktiv

Vis, eller rediger en webhook

Webhooks kan redigeres og gemmes når som helst, og når du gemmer en ny konfiguration, træder denne ændring i kraft med det samme.

Kun parametrene Begivenheder og Meddelelser kan redigeres.

Hvis navnet, omfanget eller URL'en skal ændres, skal der oprettes en ny webhook.

Sådan redigerer du parametrene for en webhook:

  • Gå til siden Webhooks 
  • Klik én gang på den webhook, du vil redigere
  • Klik på Vis/rediger under overskriftsrækken

 

  • Anvend de nødvendige ændringer, og klik på Gem

Slet en webhook

En webhook kan slettes når som helst.

Sletning af en webhook ødelægger den i systemet, så webhook'en hverken kan gendannes eller slettes.

Webhooks skal ikke deaktiveres først.

Sådan slettes en webhook:

  • Gå til Webhooks
  • Vælg det webhook, du vil slette, ved at klikke på det
  • Klik på Slet under overskriftsrækken
  • Du bliver spurgt, om du ønsker at slette webhook'en. klik på OK

Anbefalede fremgangsmåder

  • Abonner på specifikke, nødvendige hændelser for at begrænse antallet af HTTPS-anmodninger til serveren – jo mere specifik du kan lave dine webhooks, jo mindre volumen skal du gennemgå.
  • Vær dubletresistent - Hvis du har mere end én app, der deler den samme webhook-URL og den samme bruger tilknyttet hver app, sendes den samme begivenhed til din webhook flere gange (én gang pr. app). I nogle tilfælde kan din webhook modtage duplikerede begivenheder. Din webhook applikation skal være tolerant over for dette og udlede af event-ID.
  • Svar altid hurtigt på webhooks – din app har kun 5 sekunder til at svare på webhook-forespørgsler. For bekræftelsesanmodningen er dette sjældent et problem, da din app ikke behøver at gøre noget rigtigt arbejde for at svare. For notifikationsanmodninger vil din app normalt gøre noget, der tager tid, som svar på anmodningen. Det anbefales at arbejde på en separat tråd eller asynkront med en kø for at sikre, at du kan svare inden for fem sekunder
  • Administrer samtidighed – når en bruger foretager en række ændringer hurtigt efter hinanden, vil din app sandsynligvis modtage flere notifikationer for den samme bruger på omtrent samme tid. Hvis du ikke er forsigtig med, hvordan du administrerer samtidighed, kan din app ende med at behandle de samme ændringer for den samme bruger mere end én gang. For at drage fordel af Acrobat Sign-webhooks skal en klar forståelse af brugen af oplysningerne forstås. Sørg for at stille spørgsmål som: 
    • Hvilke data vil du returnere i nyttedataene? 
    • Hvem får adgang til disse oplysninger? 
    • Hvilke beslutninger eller rapporter bliver der genereret?
  • Anbefalinger til modtagelse af et underskrevet dokument – der er flere faktorer, der skal overvejes, når du beslutter, hvordan du modtager en underskrevet PDF fra Acrobat Sign i dit dokumenthåndteringssystem.

Selvom det er helt acceptabelt at vælge muligheden Aftalesigneret dokument, mens du opretter en webhook, kan du overveje at bruge Acrobat Sign API til at hente dokumenterne, når en udløsende begivenhed (såsom aftalestatus Komplet) modtages.

Ting at huske på ...

JSON størrelsesbegrænsning

JSON nyttelasten er begrænset til 10 MB.

Hvis en begivenhed genererer en større nyttelast, vil en webhook blive udløst, men de betingede parameterattributter, hvis der i anmodningen, vil blive fjernet for at reducere størrelsen af nyttelasten. 

"ConditionalParametersTrimmed " vil blive returneret i svaret, når dette sker for at informere klienten om, at  conditionalParameters info er blevet fjernet.

“conditionalParametersTrimmed” er et array-objekt, der indeholder oplysninger om de nøgler, der er blevet trimmet.

Trunkeringen vil blive udført i følgende rækkefølge :

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Underskrevne dokumenter afkortes først, efterfulgt af deltageroplysninger, dokumentoplysninger og endelig detaljerede oplysninger.

Dette kan f.eks. ske på en aftalefuldførelseshændelse, hvis den omfatter underskrevet dokument (base 64-kodet) samt for en aftale med flere formularfelter

Webhook-meddelelser

Acrobat Sign-webhooks leverer meddelelser, der gælder for alle deltagere i en aftale, hvis der er konfigureret en webhook til den pågældende bruger, deres gruppe eller deres konto.

Aftalebegivenheder behandles på en sådan måde, at hvis der er konfigureret en webhook for den relevante deltager i begivenheden, sendes en meddelelse til webhook-URL'en. Med andre ord bliver webhooks udløst for begivenheder i alle gældende aftaler, selv dem uden for den gruppe eller konto, hvor webhook er konfigureret.

Meddelelser leveres kun for de begivenheder, som deltageren er involveret i. F.eks. modtager Afsenderen af en aftale næsten alle meddelelser, mens Modtagerne kun modtager meddelelser fra starten af deres deltagelse i aftalen, og kun for de begivenheder, som de er involveret i.

Webhook-meddelelser følger den aktuelle godkendelses- og synlighedsmodel for selve Acrobat Sign, hvilket betyder, at brugerne først har adgang til aftalen, når brugerens deltagelse i en aftale er startet.

Afsenderen sender en aftale til underskrivelse til tre underskrivere.

  • Der er et WebhookX på kontoniveau, som er konfigureret til Afsenderkontoen.
  • Signerer1 er medlem af den samme konto som Afsender, men i en anden Gruppe, og der er konfigureret en WehbhookY til denne gruppe.
  • Signerer2 er medlem af en anden konto, og der er konfigurereet et WebhookZ til Signerer2-kontoen.
  • Signerer3 er medlem af den samme konto som en afsender.

Afsenderen sender en aftale: WebhookX udløser på "Aftale oprettet" og "Aftale sendt", mens WebhookY udløser på "Aftale sendt".

Signerer1-tegn: WebhookX udløser på "Aftale deltager afsluttet" og "Aftale sendt", WebhookY udløser på "Aftale deltager afsluttet" og WebhookZ udløser på "Aftale sendt".

Signerer2-tegn: WebhookX udløser på "Aftaledeltageren fuldført" og "Aftalen sendt", mens WebhookZ sender meddelelse om "Aftaledeltageren fuldført".

Signerer3-tegn: WebhookX udløser på "Aftaledeltager fuldført" og "Aftalens arbejdsgang fuldført", WebhookY udløser på "Aftalens arbejdsgang fuldført", og WebhookZ udløser på "Aftalens arbejdsgang fuldført".

Prøv igen, når lyttetjenesten er nede

Hvis mål-URL'en til webhooken er nede af en eller anden grund, sætter Acrobat Sign JSON i kø og prøver igen i en progressiv cyklus over 72 timer.

De ikke-leverede hændelser forbliver i en "forsøg igen"-kø, og der gøres den bedste indsats i løbet af de næste 72 timer for at levere notifikationerne i den rækkefølge, de opstod i.

Strategien for at prøve at levere notifikationer igen er en fordobling af tiden mellem forsøg, startende med et interval på 1 minut, der stiger til hver 12. time, hvilket resulterer i 15 forsøg i løbet af 72 timer.

Hvis webhook-modtageren ikke svarer inden for 72 timer, og der ikke har været nogen vellykkede notifikationsleverancer inden for de sidste syv dage, deaktiveres webhooken. Der sendes ingen notifikationer til denne webadresse, før webhook er aktiveret igen.

Alle meddelelser mellem den tid webhook er deaktiveret og derefter aktiveret går igen tabt.

Adobe-logo

Log ind på din konto

Hurtige links

Se alle dine planer Administrer dine planer

Juridiske meddelelser    |    Online fortrolighedspolitik