Konfigurere webhook

Oversikt

En webhook er en brukerdefinert HTTPS-tilbakeringing som utløses når en bestemt hendelse oppstår på kildeområdet (Adobe Acrobat Sign i dette tilfellet).

En webhook er faktisk bare en webtjeneste som godtar HTTPS POST-forespørsler fra en kilde. Så en webhook er en REST-tjeneste som aksepterer data eller en datastrøm.

Webhooks brukes til service til service -kommunikasjon i en Push-modell.

Når en utløserhendelse oppstår, konstruerer Acrobat Sign en HTTPS POST med en JSON-tekst og leverer den til den angitte URL-adressen.

 

Webhooks tilbyr flere fordeler i forhold til den forrige tilbakekallingsmetoden. Noen av disse er:

  • Administratorer kan aktivere sine egne webhooks uten å måtte involvere Acrobat Sign-støtte for å vise URL-adressen for tilbakeringing
  • Webhooks er bedre når det gjelder «dataferskhet», effektiviteten i kommunikasjon og sikkerhet. Ingen avspørring påkrevd
  • Webhooks tillater enkel ulike nivåer av omfang (konto/gruppe/bruker/ressurs). 
  • Webhooks er en mer moderne API-løsning, som muliggjør enklere konfigurasjon til moderne programmer
  • Flere webhooks kan konfigureres per område (konto/gruppe/bruker/ressurs), der tilbakeringinger måtte være unike
  • Webhooks gjør det mulig å velge dataene som skal returneres, der tilbakeringinger er en «alt eller ingenting»-løsning
  • Metadata som bæres med en webhook kan konfigureres (grunnleggende eller detaljert)
  • Webhooks er langt enklere å opprette, redigere eller deaktivere etter behov, siden brukergrensesnittet er fullstendig under administratorens kontroll.
Merk:

Dette dokumentet er primært fokusert på Webhooks-grensesnittet i Acrobat Sign-webprogrammet (tidligere Adobe Sign).

Utviklere som ser etter API-detaljer, kan finne mer informasjon her:


Hvordan den brukes

Administratorer må først ha en webhook-tjeneste, klar til å godta innkommende push fra Acrobat Sign. Det er mange alternativer i denne forbindelse, og så lenge tjenesten kan godta POST- og GET-forespørsler, vil webhooken være vellykket.

Når tjenesten er på plass, kan en Acrobat Sign-administrator opprette en ny webhook fra Webhook-grensesnittet i Konto-menyen på Acrobat Sign-området.

Administratorer kan konfigurere webhooken til å utløse for avtale-, webskjema- eller send samlet-hendelser.

Omfanget av webhooken kan inkludere hele kontoen eller individuelle grupper gjennom administratorgrensesnittet. Bruker- og ressursomfang er også mulig gjennom API-et

Datatypen som pushes til nettadressen, kan konfigureres og kan inkludere ting som avtaleinformasjon, deltakerinformasjon, det signerte dokumentet og så videre.

Når webhooken er konfigurert og lagret, vil Acrobat Sign pushe et nytt JSON-objekt til den definerte URL-adressen hver gang utløserhendelsen er fanget. Ingen pågående manipulering av webhooken er nødvendig med mindre du vil endre hendelsesutløserkriteriene eller JSON-nyttelasten.


Bekreftelse av hensikten med webhook-URL-adressen

Før en webhook registreres, bekrefter Acrobat Sign at webhook-URL-adressen som er angitt i registreringsforespørselen, virkelig har til hensikt å motta varsler eller ikke. For dette formålet, når en ny webhook-registreringsforespørsel mottas av Acrobat Sign, sender den først en bekreftelsesforespørsel til webhook-nettadressen. Denne bekreftelsesforespørselen er en HTTPS GET-forespørsel sendt til webhook-URL-adressen. Denne forespørselen har en tilpasset HTTP-topptekst X-AdobeSign-ClientId. Verdien i denne toppteksten er satt til klient-ID (program-ID) for API-programmet som forespør å opprette/registrere webhook. For å lykkes med å registrere en webhook svarer webhook-URL-adressen på denne bekreftelsesforespørselen med en 2XX-svarkode OG den MÅ dessuten sende tilbake samme klient-ID-verdi på én av følgende to måter:

  • Enten i et svarhode X-AdobeSign-ClientId. Dette er det samme hodet som sendes i forespørselen, og blir gjentatt i svaret.
  • I JSON-svarteksten med nøkkelen til xAdobeSignClientId og tilhørende verdi er den samme klient-ID-en som sendes i forespørselen.

Webhooken vil bare bli registrert på et vellykket svar(2XX svarkode) og validering av klient-ID enten i toppteksten eller svarteksten. Hensikten med denne bekreftelsesforespørselen er å vise at webhook-URL-adressen din virkelig ønsker å motta varsler på denne URL-adressen. Hvis du ved et uhell skrev inn feil URL-adresse, vil URL-adressen ikke svare riktig på bekreftelsen av hensiktsforespørselen, og Acrobat Sign vil ikke sende noen varsler til den URL-adressen. I tillegg kan webhook-URL-adressen også bekrefte at den bare vil motta varsler gjennom webhookene som er registrert av et bestemt program. Dette kan gjøres ved å validere klient-ID-en for programmet som er sendt i X-AdobeSign-ClientId-hodet. Hvis webhook URL-adressen ikke gjenkjenner klient-ID-en, MÅ DEN IKKE svare med suksessresponskoden, og Acrobat Sign vil sørge for at URL-adressen ikke er registrert som en webhook.

Verifisering av webhook URL-kall vil bli foretatt i følgende scenarier:

  • Registrerer Webhook: Hvis denne verifiseringen av webhook-nettadressekall mislykkes, blir ikke webhook opprettet
  • Oppdaterer Webhook: INAKTIV til AKTIV: Hvis denne bekreftelsen av webhook-nettadressekall mislykkes, endres ikke webhook-tilstanden til AKTIV

Slik svarer du på et webhook-varsel

Acrobat Sign utfører en implisitt intensjonsbekreftelse i hver webhook-varslingsforespørsel som sendes til webhook-nettadressen. Dermed inneholder hver webhook-varsling HTTPS-forespørsel også det egendefinerte HTTP-hodet kalt X-AdobeSign-ClientId. Verdien av denne overskriften er klient-IDen (Applikasjon-ID) til applikasjonen der webhooken ble opprettet. Vi vil vurdere webhook-varselet levert hvis, og bare hvis et vellykket svar (2XX svarkode) returneres og klient-IDen sendes enten i HTTP-headeren (X-AdobeSign-ClientId) eller i en JSON-responstekst med nøkkelen som xAdobeSignClientId og verdi som samme klient-ID, ellers vil vi prøve å levere varselet til webhook-nettadressen til forsøkene er utløpt.

Som nevnt ovenfor bør overskriften 'X-AdobeSign-ClientId' som er inkludert i hver varslingsforespørsel fra Sign, verdien for denne overskriften (klient-ID) gjentas som svar på to måter:

1. HTTP-header X-AdobeSign-ClientId og verdi som denne klient-ID-en

Eksempel på Javascript-kode for å hente klient-ID-en, validere den og så returnere den i svarhodet

// Hent klient-ID

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

 

//Valider den

if (clientid ==="BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

{

    //Returner den i svarhode

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

    response.status = 200;  // standardverdi

}

Eksempel PHP-kode for å hente klient-IDen, validere den og så returnere den i svarhodet

 

<?php

// Hent klient-ID

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valider den

if($clientid == "BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

{

    //Returner den i svarhode

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

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

}

?>

 


2. JSON-responstekst med nøkkel som xAdobeSignClientId og verdi som samme klient-ID

Eksempel på Javascript-kode for å hente klient-ID-en, validere den og returnere den i svarteksten

// Hent klient-ID

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

 

 

//Valider den

if (clientid ==="BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Returner klient-ID i brødteksten

                       };

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

    response.body = responseBody;

    response.status = 200;

}

Eksempel PHP-kode for å hente klient-IDen, validere den og returnere den i svarteksten

<?php

// Hent klient-ID

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Valider den

if($clientid == "BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

{

   //Returner den som svartekst

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

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

   echo json_encode($body);

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

}

?>

Eksempel på JSON-kroppen i responsen

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Forutsetninger

Du trenger:

  1. En Microsoft-konto med lisens til å opprette Azure-funksjonsprogrammer
  2. Et eksisterende Azure-funksjonsprogram, du kan opprette et ved hjelp av https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function 
  3. Grunnleggende kunnskap om Javascript, slik at du kan forstå og skrive koden på et hvilket som helst språk du ønsker


Trinn for å opprette en Azure Functions Trigger som fungerer som en Acrobat Sign webhook

For å opprette en Javascript HTTP-utløserfunksjon:

1. Logg inn via din Microsoft-konto https://portal.azure.com/

2. Åpne Azure-funksjonsapplikasjon som vises under kategorien Funksjonsprogrammer.

Dette vil åpne listen over Azure-funksjonsprogrammer:

3. Velg applikasjonen hvor du vil opprette denne nye funksjonen.

4. Klikk på Opprett (+)-knappen for å opprette en ny Azure-funksjon

 

5. Velg Webhook + API som scenario og Javascript som språk

6. Klikk på Opprett denne funksjonen

Det opprettes en ny funksjon som har mulighet til å håndtere en innkommende API-forespørsel.


Legg til logikk for å registrere Acrobat Sign webhook

Før en webhook registreres, bekrefter Acrobat Sign at webhook-URL-adressen som er angitt i registreringsforespørselen, virkelig har til hensikt å motta varsler eller ikke. For dette formålet, når en ny webhook-registreringsforespørsel mottas av Acrobat Sign, sender den først en bekreftelsesforespørsel til webhook-nettadressen. Denne bekreftelsesforespørselen er en HTTPS GET-forespørsel sendt til webhook-URL-adressen med et tilpasset HTTP-hode X-AdobeSign-ClientId. Verdien i denne overskriften settes til klient-ID for applikasjonen som ber om å opprette/registrere webhook. For å lykkes med å registrere en webhook svarer webhook-URL-adressen på denne bekreftelsesforespørselen med en 2XX-svarkode, OG kan dessuten sende tilbake samme klient-ID-verdi på én av følgende to måter.

Det er to alternativer du kan følge:


Alternativ 1: Send klient-ID i X-AdobeSign-ClientId som svarhode

Send X-AdobeSign-ClientId i svarhodet. Det er det samme hodet som sendes i forespørselen, og det må bli gjentatt i svaret.

Erstatt Index.js-filen med følgende:

module.exports = function (context, req) {

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

    // Bekreft at den innkommende klient-ID-en er ekte

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

        context.res = {

            // status: 200, /* Standard er 200 */ // hvilket som helst 2XX-svar er akseptabelt

           body: "Varsel godtatt",

            headers : {

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

            }

        };

    }

    else {

        context.res = {

          status: 400,

            body: "Oi!! Ugyldig oppkall identifisert"

        };

    }

    context.done();

};

 

Test adferden ved å etterligne anmodningen:

1. Klikk på Test-knappen ytterst i høyre hjørne

2. Etterligne dummy-forespørselen

Selv om svarhoder ikke vises ovenfor, men du kan observere det ved å etterligne det med postman/DHC eller en annen tjeneste.


Alternativ 2: Send klient-ID i svarteksten med nøkkelen xAdobeSignClientId

I JSON-svarteksten med nøkkelen xAdobeSignClientId og tilhørende verdi som er den samme klient-ID-en som sendes i forespørselen.

Erstatt Index.js-filen med følgende:

module.exports = function (context, req) {

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

    // Bekreft at den innkommende klient-ID-en er ekte

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

        context.res = {

            // status: 200, /* Standard er 200 */ // hvilket som helst 2XX-svar er akseptabelt

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

          status: 400,

            body: "Oi!! Ugyldig oppkall identifisert"

        };

    }

    context.done();

};

 

Test oppførselen ved å etterligne forespørselen

1. Klikk på Test-knappen ytterst i høyre hjørne

2. Etterligne dummy-forespørselen

Vær også oppmerksom på at samme atferd for klient-ID forventes når Webhook-URL-en mottar POST-varsler. 


Klar til bruk

Når du har bekreftet atferden, fungerer webhook-URL-adressen i henhold til Acrobat Sign-standardene. Du kan videre oppdatere den egendefinerte logikken i henhold til dine krav.

 

Hent funksjonens URL-adresse

  • Klikk på Hent funksjon-URL

 

Kopier URL-adressen og bruk den til å opprette webhooks i Acrobat Sign.

Opprette AWS Lambda-funksjonen

Hvis du vil opprette en AWS Lambda-funksjon, logger du på AWS Management Console og velger AWS Lambda-tjenesten fra tjenestelisten.

  • Klikk på Opprett en Lambda-funksjon ved hjelp av «Forfatt fra bunnen av»-alternativet
  • På siden Konfigurer funksjon angir du funksjonsnavnet «lambdaWebhooks» og velger Node.js 4.3 som kjøretid
  • For rollen velger du en eksisterende rolle eller opprett en ny rolle fra mal(er)
    • Hvis du har valgt  Opprett ny rolle fra mal(er), skriver du inn et rollenavn (f.eks. rolle-lamda) og velger Simple Microservices-tillatelser fra Policymaler-listen
  • Klikk på Opprett funksjon-knappen

  • På den nye AWS lamda-funksjonssiden velger du «Rediger innebygd kode»som «Kodeoppføringstype», beholder du indeksbehandleren som Behandler.
  • Legg til logikk for å registrere Acrobat Sign-webhooken

    Før en webhook registreres, bekrefter Acrobat Sign at webhook-URL-adressen som er angitt i registreringsforespørselen, virkelig har til hensikt å motta varsler eller ikke. For dette formålet, når en ny webhook-registreringsforespørsel mottas av Acrobat Sign, sender den først en bekreftelsesforespørsel til webhook-nettadressen. Denne bekreftelsesforespørselen er en HTTPS GET-forespørsel sendt til webhook-URL-adressen med et tilpasset HTTP-hode X-AdobeSign-ClientId. Verdien i denne overskriften settes til klient-ID for applikasjonen som ber om å opprette/registrere webhook. For å lykkes med å registrere en webhook svarer webhook-URL-adressen på denne bekreftelsesforespørselen med en 2XX-svarkode, OG kan dessuten sende tilbake samme klient-ID-verdi på én av følgende to måter.Vær også oppmerksom på at samme atferd for klient-ID forventes når Webhook-URL-en mottar POST-varsler. 

    Følg en av de to sakene:

    Sak 1: Send klient-ID i X-AdobeSign-ClientId som svarhode

    •  Send X-AdobeSign-ClientId i svarhodet. Det er det samme hodet som sendes i forespørselen, og det må bli gjentatt i svaret.

      Kodebiten
      I index.js-filen erstatter du den automatisk genererte kodebiten med følgende kode:

Eksempelnode JS-kode for å hente klient-ID-en, validere den og deretter returnere den i svarhodet

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

  // Hent klient-ID

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

 

  //Valider den

  if (clientid =="BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oi!! illegitimate call");

  }

}

 

Tilfelle 2: Pass klient-ID i svarteksten med nøkkelen xAdobeSignClientId

I JSON-svarteksten med nøkkelen xAdobeSignClientId og tilhørende verdi med den samme klient-ID-en som sendes i forespørseltoppteksten.

 

Kodesnutt

Erstatt Index.js-filen med følgende :

Eksempelnode JS-kode for å hente klient-ID-en, validere den og deretter returnere den i svarhodet

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

 // Hent klient-ID

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

  

 //Valider den

 if (clientid =="BGBQIIE7H253K6") //Erstatt 'BGBQIIE7H253K6' med klient-ID-en til programmet der webhooken opprettes

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Oi!! illegitimate call");

  }

}

  • Lagre funksjonen. Lambda-funksjonen er opprettet, og vi er nesten klar til å bruke den i en sanntids webhook.

 

Konfigurere AWS API Gateway

For å gjøre denne Lambda offentlig tilgjengelig gjennom en HTTP-metode, må vi konfigurere AWS API Gateway ved hjelp av vår funksjon (opprettet ovenfor) som serverenden for API.

I AWS Management Console velger du API Gateway fra AWS-tjenestene og klikker på Opprett API-knappen

  • På siden Opprett nytt API velger du Nytt API og angir webhooks som API-navn.
  • Klikk på Opprett API-knappen
  • Velg rullegardinlisten Handlinger og velg alternativet Opprett ressurs
  • Merk av for alternativet Konfigurer som proxy-ressurs og angi valider som ressursnavn og {proxy+} i ressursbanen
  • La alternativet Aktiver API Gateway CORS være umarkert og klikk på knappen Opprett ressurs
  • Hold Lambda-funksjonsproxyen valgt som integrasjonstype og velg regionen der du har opprettet Lambda-funksjonen i rullegardinlisten for Lambda-regionen (sannsynligvis er det den samme regionen der du oppretter API-gatewayen).
  • Angi valider som Lambda-funksjonen og klikk på Lagre-knappen
  • I popup-vinduet Legg til tillatelse til Lambda-funksjon, velger du OK

Hvis alle trinnene ovenfor blir utført, ser du noe som dette:

Distribuerer API

Neste trinn er å distribuere dette API-et slik at det blir klart til bruk.

  • I rullegardinmenyen Handlinger, velger du Distribuer API
  • Velg [Nytt trinn] i distribusjonstrinnet og angi prod (eller det du vil identifisere dette trinnet som) i fasenavnet
  • Klikk på Bruk-knappen

API er nå klart til bruk, og du kan finne start-nettadressen i den blå boksen som vist nedenfor:

Legg merke til denne nettadressen fordi du må oppgi den som nettadressen din i sanntid.

 

Klar til bruk

Det er gjort. Bruk denne nettadressen ovenfor med «/{nodeJSfunctionName}» vedlagt som webhook-nettadresse i POST /webhooks API-forespørsel.  Når du har bekreftet atferden, fungerer Webhook-nettadressen i henhold til
Acrobat Sign – standarder. Du kan videre oppdatere/legge til den egendefinerte logikken i henhold til ditt krav.


Konfigurasjonsalternativer

Konfigurasjon av Webhook krever at fem elementer defineres:

  • Navn – Det foreslås et intuitivt navn som andre administratorer lett kan forstå
  • Omfang – Hvor bredt nett skal webhooken fange. Konto og gruppe er tilgjengelig i grensesnittet
    • API-et støtter omfangene Konto, Gruppe, Bruker og Ressurs
    • Bare ett omfang per webhook kan defineres
  • Nettadresse – Måladressen som Acrobat Sign sendte JSON-nyttelasten til
  • Hendelser – Utløseren som får Acrobat Sign til å bygge JSON og sende til nettadressen
    • Hver hendelse bygger en ny nyttelast som er relevant for utløserhendelsen
    • Flere hendelser kan inkluderes i én webhook
  • Varslingsparametere – Varslingsparametrene identifiserer delene av Hendelse JSON-nyttelasten, slik at du kan velge bare delene av Hendelsen som er viktige for denne webhooken (og dermed redusere unødvendige data i til nettadressen din).

 

Når webhooken er fullt definert, klikker du på Lagre og den nye webhooken begynner å reagere for å utløse hendelser umiddelbart. 

Merk:

Konfigurer webhook-nettadressen for å svare på webhook-bekreftelses- og webhook-varslingsforespørsler i henhold til bekreftelsesprotokollen som er forklart ovenfor. Klient-ID-en (applikasjons-ID) som vil bli sendt til webhooks opprettet fra Acrobat Sign-webapplikasjonen vil være – UB7E5BXCXY

Konfigurer webhooken


Omfang

  • Konto: Alle de abonnerte hendelsene som oppstår i kontoen, utløser push 
    • Kontoadministratorer har myndighet til å se alle webhooks definert for kontoen/alle gruppene.
  • Gruppe: Alle abonnerte hendelser som forekommer i den gruppen, utløser push. Webhooks med gruppekopling finnes bare i én gruppe.
    • Gruppeadministratorer vil bare se webhookene som er dedikert til gruppen. De kan ikke se webhooks på kontonivå eller webhooks som er bundet til andre grupper.
    • Kontoer som har brukere i flere grupper aktivert, vil se alternativet for å angi gruppen omfanget skal brukes på.
  • Brukerkonto: Alle abonnerte hendelser for en brukerkonto utløser push. Webhooks på brukernivå kan bare opprettes via API.
  • Webhook på ressursnivå: Dette vil bli opprettet for en bestemt ressurs. Hendelser som er spesifikke for denne ressursen, vil bli flyttet til webhook-nettadressen. Ressursbaserte webhooks kan bare opprettes via API.


Nettadresse

En webhook-nettadresse er en server som lytter etter innkommende HTTPS POST-varslingsmeldinger som utløses når hendelser inntreffer.

Du må ha denne nettadressen for å abonnere på din webhook for hendelser.

  • Klienten må inkludere en HTTPS-URL som Acrobat Sign kan POST til. Denne nettadressen må være tilgjengelig på det offentlige internett.  
    • For eksempel vil ikke 127.0.0.1 og localhost-URI-er fungere.
    • Nettadressesluttpunktet må lytte på port 443.
  • Kontroller at webhook støtter POST-forespørsler for innkommende hendelsesvarsler og FÅR forespørsler om bekreftelsesforespørselen.
  • Nettadressen bør ikke blokkeres av en brannmur.


Hendelser

Nedenfor er hendelsene som kan utløse en push til webhook-nettadressen, gruppert etter objektet.

Hver hendelse har en mal for JSON-nyttelast som kan leveres. (Klikk på navnet på hendelsen for å se nyttelastdetaljene):

  • Send samlet (tidligere megasigner) – Send samlet-hendelser gjelder bare opprettelsen av overordnet Send samlet-objekt. De resulterende barneavtalene spores som avtalehendelser.  
    • Send alle hendelser samlet – Alle hendelser som Sendes samlet er inkludert. Hvis flere hendelser defineres i fremtiden, blir de automatisk inkludert i denne innstillingen.  JSON-nyttelasten er basert på den enkelte hendelsen som utløses
    • Send samlet opprettet – Når en Send samlet opprettes
    • Send samlet delt – Når en Send samlet er delt
    • Send samlet tilbakekalt – Når en Send samlet tilbakekalles.
  • Webskjema (tidligere Widget) – Webskjemahendelser gjelder bare opprettelse av webskjemamalen. De resulterende underordnede avtalene spores som avtalehendelser.
    • Widget for alle hendelser – Alle webskjemahendelser er inkludert. Hvis flere hendelser defineres i fremtiden, blir de automatisk inkludert i denne innstillingen.  JSON-nyttelasten er basert på den enkelte hendelsen som utløses
    • Widget opprettet – Når et webskjema opprettes
    • Widget aktivert – Når et webskjema er aktivert
    • Widget deaktivert – Når et webskjema er deaktivert
    • Widget endret – Når et webskjema endres
    • Kontrollprogram delt – Når et webskjema deles
    • Oppretting av kontrollprogram mislyktes – Når et webskjema automatisk avbrytes på grunn av et konverteringsproblem


Varslingsparametere

Med varslingsparametere kan du tilpasse JSON-nyttelasten til bare spesifikke elementer i hendelsen.

I en hendelse som er erstattet av en avtaledeltaker, kan det for eksempel hende at du bare vil ha avtaleinformasjonen og deltakerinformasjonen, mens dokumentinformasjonen utelates og reduserer det totale volumet i webhook-nettadressen din

 

  • Avtale
    • Avtaleinfo – Detaljert avtaleinformasjon basert på avtalens tilstand på tidspunktet for utløsende hendelse
    • Informasjon om avtaledokument – Inkluderer all dokumentinformasjon som genereres som et resultat av hendelsen
    • Informasjon om avtaledeltaker – Inkluderer eventuell deltakerinformasjon som et resultat av arrangementet
    • Avtale signert dokument – Gir det signerte PDF-dokumentet. 
      • Gjeldende for Arbeidsflytsavtalen gjennomført og Avtale alle hendelser.
  • Send samlet
    • Send samlet-info – Detaljert informasjon om Send samlet-objektet som utløste hendelsen
  • Nettskjema
    • Widget-info – Detaljert informasjon om webskjemaet som utløste hendelsen
    • Widget-dokumentinformasjon – Dokumentinformasjonen som er knyttet til webskjemamalen
    • Widget-deltakerinfo – Informasjon om de definerte deltakerne i webskjemamalen


Toveis SSL-godkjenning

Toveis SSL, ofte kalt klientside-SSL, er en SSL-modus der både serveren og klienten (nettleseren) presenterer sertifikater for å identifisere seg.

Kontoadministratorer kan konfigurere et sertifikat på klientsiden på siden med Sikkerhetsinnstillinger.

Acrobat Sign bekrefter SSL-sertifikatene ved levering av nyttelaster til webhook-nettadressen. Webhooks som feiler SSL-sertifikatbekreftelsen vil ikke levere JSON-nyttelasten. 

Bruk toveis SSL for å godkjenne klienten (Acrobat Sign) og lyttetjenesten for å sikre at bare Acrobat Sign kan nå webhook-nettadressen din. 

Hvis webhooken ble opprettet av en Partnerapplikasjon, vil webhooken bruke et klientsertifikat (hvis tilgjengelig) fra partnerapplikasjonens konto til å identifisere seg når den foretar tilbakeringinger fra webhook.

Nedenfor er de vanligste spørsmålene for både webserverbekreftelsesprosessen og klientsertifiseringsbekreftelsen.

Bekreftelse av nettserver

Under registreringen av en webhook bekrefter Acrobat Sign webhook-server-URL-en.

Kundene vil ikke kunne registrere webhook hvis tilkoblingen til webhook-tilbakeringingsadressen ikke kan fullføres fra Acrobat Sign.

Nei.

URL-adressen for tilbakeringing til webhook kan bare være HTTPS på port 443.

Acrobat Sign blokkerer utgående HTTPS-trafikk til alle andre porter.

En god måte å bekrefte serversertifikatet på er å bruke diagnoseverktøyet DigiCert® SSL Installation Diagnostics Tool.

Oppgi bare vertsnavnet, f.eks.: www.digicert.com

Vanlige problemer inkluderer:

  • Problem: Bruke ikke-klarert sertifiseringsinstans eller et selvsignert sertifikat

Løsning: Bruk et offentlig CA-utstedt SSL-sertifikat for servren for webhook-tilbakeringing.

Ikke-klarert sertifiseringsinstans

  • Problem: Serveren sender ikke det mellomliggende sertifikatet

Løsning: Installer de mellomliggende sertifikatene på serveren for webhook-tilbakeringing.

Du finner mer informasjon på https://www.digicert.com/kb/ssl-certificate-installation.htm.

Manglende mellomliggende sertifikater

Klientsertifikatbekreftelse

For å kunne sette opp en toveis SSL for en webhook, krever vi at administratoren laster opp en .p12 (eller .pfx)-fil som inneholder den private nøkkelen. Filen lagres sikkert i kundekontoen, og administratoren har full kontroll for å fjerne den når som helst.

I et toveis webhook-oppsett er Acrobat Sign oppringeren/klienten og trenger den private nøkkelen for å bevise at samtalen er foretatt av Acrobat Sign på vegne av kundekontoen.

  1. Kontroller at toveis SSL er aktivert

    Toveis SSL må være aktivert på serveren for webhook-tilbakeringing.

    Koble til webhook-adressen for tilbakeringing ved hjelp av en hvilken som helst nettleser. Du bør få:

    400 Feil i forespørsel
    Ingen nødvendig SSL-sertifikat sendt

    Dette betyr at serveren forventer at klienten sender klientsertifikater (dvs. at toveis SSL er aktivert for serveren).

    Hvis du ikke ser meldingen ovenfor, er ikke toveis SSL aktivert.

    Merk:

    Du kan bruke Postman, og gjøre en postforespørsel til URL for webhook-tilbakeringing. Du bør få et lignende resultat.

  2. Bekreft klientsertifikat lokalt

    Klientlegitimasjonen kan enten være et selvsignert sertifikat eller et sertifikat utstedt av sertifiseringsinstanssen. Den må imidlertid minst oppfylle følgende krav: X.509 v3-utvidelser:

    X.509 v3-utvidelse

    Verdi

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    Klientsertifikatet må være en PKCS12-fil med filtypen .p12 eller .pfx, og det må inneholde både klientsertifikatet (slik at serveren kan bekrefte identiteten til klienten) og klientens private nøkkel (slik at klienten digitalt kan signere meldinger som serveren kan bekrefte under SSL-håndtrykket). 

    Bruk kommandoen openssl for å bekrefte filen p12 (pfx):

    openssl pkcs12 -info -in outfile.p12

    Det bør bes om passordet for den private nøkkelen. Utdataene skal inneholde både sertifikater og en kryptert privat nøkkel 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-----

    Sertifikatene bør minst omfatte sertifikatet for sluttenhet og de mellomliggende sertifikatene. Ideelt sett vil den også inneholde root CA-sertifikatet.  

    Kontroller at .p12- eller .pfx-filen er passordbeskyttet.

  3. Opprett et selvsignert klientsertifikat (valgfritt)

    Klientsertifikater kan enten være CA-utstedt eller selvsignert, avhengig av ditt behov.

    Bruk følgende openssl-kommando for å generere et selvsignert klientsertifikat:

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

    Forsiktig!

    Hold de resulterende filene hemmelige ettersom de er dine selvsignerte sertifikater.

    Deretter genererer du klientfilen .p12:

    1. Generer en privat nøkkel for SSL-klienten:

      openssl genrsa -out client.key 2048

    2. Bruk klientens private nøkkel til å generere en sertifikatforespørsel:

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

    3. Utsted klientsertifikatet ved hjelp av sertifikatforespørselen og CA-sertifikatet/nøkkelen:

      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 klientsertifikatet og den private nøkkelen til pkcs#12-format for bruk i nettlesere:

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

    5. Fjern klientens private nøkkel, klientsertifikat og klientforespørselsfiler ettersom pkcs12 har alt du trenger.

      rm client.key client.cer client.req

  4. Kontroller klientsertifikatet mot den eksterne serveren

    • Bruk Postman til å laste inn klientens PFX-fil i Innstillinger > Sertifikater.
    • Velg Legg til sertifikat for å legge til klientsertifikatet.
    Postman-innstillinger

    • Konfigurer HTTP-hodet for x-adobesign-clientid:
    Konfigurer toppteksten

    Når den er konfigurert, sender du en postforespørsel til webhook callback-nettadresse.

    Du burde få 200 svar.

  5. Hvorfor avviser Acrobat Sign PFX-filen min selv etter at jeg har bekreftet den med Postman?

    Hvis du har fulgt prosessen ovenfor for bekreftelse av pfx-fil, og Acrobat Sign fremdeles avviser pfx-filen, er det sannsynlig at filen ble generert av et Microsoft-verktøy som kan produsere en PKCS12-fil som ikke er standard.

    I så fall kan du bruke kommandoene nedenfor for å pakke ut sertifikatene og den private nøkkelen fra pfx-filen, og deretter generere en riktig formatert PKCS12-fil:

    // Trekk ut sertifikater og privat nøkkel 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
    
    // Opprett ny PKCS12-fil
    openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx


Hvordan aktivere eller deaktivere

Tilgang til Webhooks-funksjonen er aktivert som standard for virksomhetsplankontoer.

Administratorer på gruppenivå kan opprette/kontrollere Webhooks som bare opererer i gruppen.

Du finner tilgang til Webhooks-siden i venstre hjørne på Admin-menyen: Konto > Webhooks


Aktivere en webhook

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

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

Slik aktiverer du en inaktiv webhook:

  • Klikk på Alternativer-ikonet (tre horisontale linjer) til høyre for overskriftsraden for webhooks, og velg Vis alle webhooks

 

  • Enkeltklikk på den inaktive webhooken for å velge den.
    • Dette viser alternativene for webhooken rett under topptekstraden
  • Klikk på Aktiver

Den aktive webhooken begynner å sende data til måladressen så snart neste hendelse utløses.


Deaktiver en webhook

Deaktivering av en webhook krever bare at du

  • Gå til Webhooks-siden.
  • Enkeltklikk på brukeren du vil deaktivere.
  • Velg Deaktiver fra menyelementene under overskriftsraden
    • Når den er deaktivert, viser webhook en status for Inaktiv


Vis eller rediger en webhook

Webhooker kan redigeres og lagres når som helst. Når du lagrer en ny konfigurasjon, trer denne endringen i kraft umiddelbart.

Bare hendelser og varslingsparametere kan redigeres.

Hvis navnet, omfanget eller nettadressen må endres, må det opprettes en ny webhook.

Slik redigerer du parameterne for en webhook:

  • Gå til Webhooks-siden. 
  • Enkeltklikk på webhooken du vil redigere.
  • Klikk på Vis/rediger-alternativet under overskriftsraden

 

  • Bruk eventuelle endringer som er nødvendige, og klikk på Lagre


Slett en webhook

En webhook kan slettes når som helst.

Hvis du sletter en webhook, ødelegges den i systemet slik at det ikke er mulig å gjenopprette en slettet webhook.

Webhooker trenger ikke å deaktiveres først.

Slik sletter du en webhook:

  • Gå til Webhooks
  • Velg webhooken du vil slette ved å klikke på den
  • Klikk på Slett-alternativet under overskriftsraden
  • En utfordring presenteres for å sikre at du ønsker å slette webhook. Klikk på OK


Anbefalte fremgangsmåter

  • Vær motstandsdyktig mot duplikater – Hvis du har mer enn én app som deler samme nettadresse og samme bruker som er tilordnet hver app, blir den samme hendelsen sendt til nettadressen flere ganger (én gang per app). I noen tilfeller kan webhooken din motta dupliserte hendelser. Webhook-applikasjonen din bør være tolerant for dette og trekke fra med hendelses-ID.
  • Svar alltid raskt på webhooks raskt – Appen din har bare ti sekunder på seg til å svare på webhook-forespørsler. Når det gjelder bekreftelsesforespørselen er dette sjelden et problem, siden appen din ikke trenger å gjøre noe ordentlig arbeid for å svare. For varslingsforespørsler vil imidlertid appen vanligvis gjøre noe som tar tid som svar på forespørselen. 

Hvis du for eksempel trenger å behandle og deretter lagre signerte dokumenter. For å være sikker på at du alltid kan svare innen ti sekunder, bør du alltid gjøre arbeidet på en separat tråd eller asynkront ved hjelp av en kø.

  • Administrer samtidighet – Når en bruker gjør en rekke endringer i rask rekkefølge, vil appen sannsynligvis motta flere varsler for samme bruker omtrent samtidig. Hvis du ikke er forsiktig med hvordan du administrerer samtidighet, kan det ende med at appen din behandler de samme endringene for samme bruker mer enn én gang. 
  • For å kunne dra nytte av webhooks for Acrobat Sign, må en klar forståelse av bruken av informasjonen forstås. Sørg for å stille spørsmål som: 

1. Hvilke data vil du returnere i nyttelasten? 

2. Hvem får tilgang til denne informasjonen? 

3. Hvilke beslutninger eller rapportering vil bli generert?

  • Anbefalinger for mottak av signert dokument – Det er flere faktorer å ta hensyn til når du bestemmer hvordan du skal motta en signert PDF fra Acrobat Sign på dokumentbehandlingssystemet. 

Selv om det er fullt akseptabelt å bare velge alternativet Signert avtaledokument mens du oppretter en webhook, kan du vurdere å bruke Acrobat Sign API for å hente dokumentene når en utløsende hendelse (for eksempel avtalestatusen Fullført) mottas.


Ting å huske på ...

JSON-størrelsesbegrensning

JSON-nyttelaststørrelsen er begrenset til 10 MB.

Hvis en hendelse genererer en større nyttelast, vil en webhook bli utløst. Men de betingede parameterattributtene, hvis de finnes i forespørselen, vil bli fjernet for å redusere størrelsen på nyttelasten. 

"ConditionalParametersTrimmed " vil bli returnert i svaret når dette skjer for å informere klienten om at  conditionalParameters  informasjonen er fjernet.

"conditionalParametersTrimmed" er et matriseobjekt som inneholder informasjon om nøklene som er trimmet.

Avkortingen vil gjøres i følgende rekkefølge:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Signerte dokumenter vil bli avkortet først, etterfulgt av deltakerinfo, dokumentinfo og til slutt detaljert informasjon.

Dette kan for eksempel skje på en avtalefullføringshendelse hvis den inkluderer signert dokument (base 64-kodet), eller for en avtale med flere skjemafelt


Varsler om webhook

Acrobat Sign-webhooks leverer varsler som er gjeldende for alle deltakere i en avtale hvis det er en webhook konfigurert for den brukeren, deres gruppe eller deres konto.

Avtalehendelser behandles på en slik måte at hvis det er konfigurert en webhook for den aktuelle deltakeren i hendelsen, sendes et varsel til denne webhook-nettadressen Med andre ord utløses webhooks for hendelser i alle gjeldende avtaler, selv de utenfor gruppen eller kontoen der webhooken er konfigurert.

Varsler leveres kun for de arrangementene som deltakeren er involvert i. F.eks. Avsenderen av en avtale mottar nesten alle varsler, mens Mottakerne bare mottar varsler fra starten av sitt engasjement i avtalen, og kun for de hendelsene de er involvert i.

Webhook-varsler følger gjeldende godkjennings- og synlighetsmodell for selve Acrobat Sign, noe som betyr at brukere vil ha tilgang til avtalen bare når brukerens deltakelse i en avtale har startet.

Avsenderen sender avtale om signering til tre underskrivere.

  • Det er et WebhookX-kontonivå konfigurert for avsenderkontoen.
  • Underskriver1 er medlem av samme konto som avsender, men i en annen gruppe, og det er konfigurert en WehbhookY for den gruppen.
  • Underskriver2 er medlem av en annen konto, og det er en WebhookZ konfigurert på kontonivå for Underskriver2-kontoen.
  • Underskriver3 er medlem av samme konto som en avsender.

Avsenderen sender en avtale: WebhookX utløses ved «Avtale opprettet» og «Avtale sendt» mens WebhookY utløses ved «Avtale sendt».

Underskriver1 signerer: WebhookX utløses ved «Avtaledeltaker fullført» og «Avtale sendt», WebhookY utløses ved «Avtaledeltaker fullført» og WebhookZ utløses ved «Avtale sendt».

Underskriver2 signerer: WebhookX utløses ved «Avtaledeltaker fullført» og «Avtale sendt», mens WebhookZ sender varsel for «Avtaledeltaker fullført».

Underskriver3 signerer: WebhookX utløses ved «Avtaledeltaker fullført» og «Avtalearbeidsflyt fullført», WebhookY utløses ved «Avtalearbeidsflyt fullført» og WebhookZ utløses ved «Avtalearbeidsflyt fullført».


Prøv på nytt når lyttetjenesten er nede

Hvis måladressen for webhooken er nede av en eller annen grunn, setter Acrobat Sign JSON i kø og prøver pushet på nytt i en progressiv syklus over 72 timer.

De uleverte hendelsene blir værende i en prøv på nytt-kø, og det gjøres en best mulig innsats i løpet av de neste 72 timene for å levere varslene i den rekkefølgen de oppsto.

Strategien for å prøve å levere varsler på nytt er en dobling av tiden mellom forsøk, og starter med et ett minutts intervall som øker til hver 12. time, og resulterer i 15 nye forsøk i løpet av 72 timer.

Hvis webhook-mottakeren ikke svarer innen 72 timer, og det ikke har vært noen vellykkede varslingsleveranser de siste syv dagene, deaktiveres webhooken. Ingen varsler vil bli sendt til denne nettadressen før webhook er aktivert igjen.

Alle varsler mellom når webhook er deaktivert og deretter aktivert igjen, vil gå tapt.

Adobe-logoen

Logg på kontoen din