Eksempel på Javascript-kode for å hente klient-ID-en, validere den og så returnere den i svarhodet
Sist oppdatert
4. jan. 2024
|
Gjelder også for Adobe Acrobat Sign
- Adobe Acrobat Sign-integrasjoner
- Nyheter
- Produktversjoner og livssyklus
- Acrobat Sign for Salesforce
- Installere pakken
- Konfigurere pakken
- Brukerhåndbok
- Aktivere digital autentisering
- Utviklerveiledning
- Veiledning for avansert tilpassing
- Veiledning for felttilordning og maler
- Brukerhåndbok for mobilapp
- Automatiseringsveiledning for flyt
- Veiledning for Document Builder
- Konfigurere store dokumenter
- Oppgraderingsveiledning
- Produktmerknader
- Vanlige spørsmål
- Veiledning for feilsøking
- Tilleggsartikler
- Acrobat Sign for Microsoft
- Acrobat Sign for Microsoft 365
- Acrobat Sign for Outlook
- Acrobat Sign for Word/PowerPoint
- Acrobat Sign for Teams
- Acrobat Sign for Microsoft PowerApps og Power Automate
- Acrobat Sign Connector for Microsoft Search
- Acrobat Sign for Microsoft Dynamics
- Acrobat Sign for Microsoft SharePoint
- Oversikt
- Lokal SharePoint: Installasjonsveiledning
- Lokal SharePoint: Veiledning for maltilordning
- Lokal SharePoint: Brukerhåndbok
- Lokal SharePoint: Produktmerknader
- SharePoint Online: Installasjonshåndbok
- SharePoint Online: Veiledning for maltilordning
- SharePoint Online: Brukerhåndbok
- SharePoint Online: Veiledning for webskjematilordning
- SharePoint Online: Produktmerknader
- Acrobat Sign for Microsoft 365
- Acrobat Sign for ServiceNow
- Acrobat Sign for HR ServiceNow
- Acrobat Sign for SAP SuccessFactors
- Acrobat Sign for Workday
- Acrobat Sign for NetSuite
- Acrobat Sign for SugarCRM
- Acrobat Sign for VeevaVault
- Acrobat Sign for Coupa BSM Suite
- Acrobat Sign for Zapier
- Utviklerdokumentasjon for Acrobat Sign
Oversikt
En webhook er en brukerdefinert HTTPS-forespørsel som utløses når en bestemt hendelse oppstår på kildeområdet (Adobe Acrobat Sign i dette tilfellet).
En webhook er ikke mer enn en REST-tjeneste som aksepterer data eller en datastrøm.
Webhooks er ment for service-til-service-kommunikasjon i en PUSH-modell.
Når en abonnert hendelse oppstår, konstruerer Acrobat Sign en HTTPS POST med en JSON-tekst og leverer den til den angitte nettadressen.
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 nettadressen for tilbakekall
- 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 av 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 tilbakekall 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- (Widget) eller send samlet- (MegaSign) hendelser. Ressursen for bibliotekmal (biblioteksdokument) kan også konfigureres via API-en.
Omfanget av webhooken kan inkludere hele kontoen eller individuelle grupper gjennom administratorgrensesnittet. API-en gir mer detaljer ved valg av BRUKER- eller RESSURS-omfang.
Datatypen som pushes til nettadressen, kan konfigureres og kan inkludere ting som avtaleinformasjon, deltakerinformasjon, dokumentinformasjon og så videre.
Når webhooken er konfigurert og lagret, vil Acrobat Sign pushe et nytt JSON-objekt til den definerte nettadressen hver gang den abonnerte hendelsen er utløst. 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 om webhook-nettadressen som er angitt i registreringsforespørselen har til hensikt å motta varsler eller ikke. For dette formålet, når Acrobat Sign mottar en ny webhook-registreringsforespørsel, 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 webhooken. For å lykkes med å registrere en webhook svarer webhook-nettadressen 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 den samme toppteksten som sendes i forespørselen, og blir gjentatt i svaret.
- Eller 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-nettadressen din virkelig ønsker å motta varsler på den nettadressen. Hvis du ved et uhell skrev inn feil nettadresse, vil nettadressen ikke svare riktig på bekreftelsen av hensiktsforespørselen, og Acrobat Sign vil ikke sende noen varsler til den nettadressen. I tillegg kan webhook-nettadressen 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-nettadressen ikke gjenkjenner klient-ID-en, MÅ DEN IKKE svare med suksessresponskoden, og Acrobat Sign vil sørge for at nettadressen ikke er registrert som en webhook.
Verifisering av webhook-nettadressekall vil bli foretatt i følgende scenarier:
- Registrerer Webhook: Hvis denne verifiseringen av webhook-nettadressekall mislykkes, blir ikke webhooken 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-ID-en sendes enten i HTTP-toppteksten (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
|
|
|---|
|
// 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:
- En Microsoft-konto med lisens til å opprette Azure-funksjonsprogrammer
- Et eksisterende Azure-funksjonsprogram, du kan opprette et ved hjelp av https://docs.microsoft.com/nb-no/azure/azure-functions/functions-create-first-azure-function
- 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:
- Send X-AdobeSign-ClientId i svarhodet. Det er det samme hodet som sendes i forespørselen, og det må bli gjentatt i svaret.
|
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-en 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
Omfang
- Konto: Alle de abonnerte hendelsene som oppstår i kontoen utløser push.
- Kontoadministratorer har myndighet til å se alle webhooks definert for kontoen og alle gruppene i den kontoen.
- Gruppe: Alle abonnerte hendelser som forekommer i den gruppen utløser push. MERK: Webhooks med gruppeomfang finnes bare for den ene gruppen.
- 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. Webhooks på ressursnivå 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.
- Nettadresse-endepunktet må lytte på port 443 eller 8443 (bestemt av kunden når vedkommende definerer tilbakekall-nettadressen).
- Kontroller at webhook støtter POST-forespørsler for innkommende hendelsesvarsler og GET forespørsler om bekreftelsesforespørselen.
- Nettadressen bør ikke blokkeres av en brannmur.
Nedenfor er hendelsene som kan utløse en push til webhook-nettadressen, gruppert etter objekt og oppført i rekkefølgen funnet i brukergrensesnittet.
Verdien til venstre er verdien du vil se i Acrobat Sign-grensesnittet. Verdien til høyre er webhook-navnet i API-en.
For fullstendige detaljer om webhooks og deres nyttelaster, kan du se Utviklerveiledning for Acrobat Sign.
Avtaler:
| UI-element | Webhook-navn |
| Avtale alle hendelser | AGREEMENT_ALL |
| Avtale opprettet | AGREEMENT_CREATED |
| Avtale sendt | AGREEMENT_ACTION_REQUESTED |
| Avtaledeltaker fullført | AGREEMENT_ACTION_COMPLETED |
| Avtalearbeidsflyt fullført | AGREEMENT_WORKFLOW_COMPLETED |
| Avtale utløpt | AGREEMENT_EXPIRED |
| Avtale slettet | AGREEMENT_DOCUMENTS_DELETED |
| Avtale kansellert | AGREEMENT_RECALLED |
| Avtale avvist | AGREEMENT_REJECTED |
| Avtale delt | AGREEMENT_SHARED |
| Avtale delegert | AGREEMENT_ACTION_DELEGATED |
| Avtaledeltaker erstattet | AGREEMENT_ACTION_REPLACED_SIGNER |
| Avtale endret | AGREEMENT_MODIFIED |
| Avtaleendring bekreftet | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
| Avtale-e-post vist | AGREEMENT_EMAIL_VIEWED |
| Avtale-e-post ble returnert | AGREEMENT_EMAIL_BOUNCED |
| Oppretting av avtale mislyktes | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Avtale synkronisert etter frakoblet hendelse | AGREEMENT_OFFLINE_SYNC |
| Avtale lastet opp av avsender | AGREEMENT_UPLOADED_BY_SENDER |
| Avtale lagt i hvelv | AGREEMENT_VAULTED |
| Avtaledeltakers sosiale identitet godkjent | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
| Avtaledeltaker KBA-godkjent | AGREEMENT_KBA_AUTHENTICATED |
| Avtalepåminnelse sendt | AGREEMENT_REMINDER_SENT |
| Avtaleunderskrivernavn endret av underskriver | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
| Avtale-webhooks er bare tilgjengelig via API | |
| I/T | AGREEMENT_EXPIRATION_UPDATED |
| I/T |
AGREEMENT_READY_TO_NOTARIZE |
| I/T |
AGREEMENT_READY_TO_VAULT |
Massesending:
| UI-element | Webhook-navn |
| Send samlet – alle hendelser | MEGASIGN_ALL |
| Send samlet – opprettet |
MEGASIGN_CREATED |
| Send samlet – delt |
MEGASIGN_SHARED |
| Send samlet – tilbakekalt |
MEGASIGN_RECALLED |
Webskjemaer:
| UI-element | Webhook-navn |
| Alle hendelser for webskjema | WIDGET_ALL |
| Webskjema opprettet |
WIDGET_CREATED |
| Webskjema aktivert |
WIDGET_ENABLED |
| Webskjema deaktivert |
WIDGET_DISABLED |
| Webskjema endret |
WIDGET_MODIFIED |
| Webskjema delt |
WIDGET_SHARED |
| Oppretting av webskjema mislyktes |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Bibliotekmaler (bare API):
| UI-element | Webhook-navn |
| I/T | LIBRARY_DOCUMENT_ALL |
| I/T | LIBRARY_DOCUMENT_CREATED |
| I/T | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| I/T | LIBRARY_DOCUMENT_MODIFIED |
Varslingsparametere
Med varslingsparametere kan du tilpasse JSON-nyttelasten til bare spesifikke elementer i hendelsen.
For eksemepel 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 den totale JSON-størrelsen som sendes til 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 nettskjemaet som utløste hendelsen.
- Widget-dokumentinformasjon – dokumentinformasjonen som er knyttet til webskjemaet.
- Widget-deltakerinfo – informasjon om de definerte deltakerne i webskjemaet.
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 ikke består 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 et Partnerprogram, vil webhooken bruke et klientsertifikat (hvis tilgjengelig) fra partnerprogrammets konto til å identifisere seg når den sender webhook-varsler.
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.
Nettadressen for twebhook-tilbakekall kan bare være HTTPS på port 443 eller 8443.
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.
- 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.
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.
-
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 POST forespørsel til URL for webhook-tilbakeringing. Du bør få et lignende resultat.
-
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.
Varsel:Kontroller at .p12- eller .pfx-filen er passordbeskyttet.
-
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:
- Generer en privat nøkkel for SSL-klienten:
openssl genrsa -out client.key 2048
- Bruk klientens private nøkkel til å generere en sertifikatforespørsel:
openssl req -new -key client.key -out client.req
- 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
- 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
- Fjern klientens private nøkkel, klientsertifikat og klientforespørselsfiler ettersom pkcs12 har alt du trenger.
rm client.key client.cer client.req
- Generer en privat nøkkel for SSL-klienten:
-
- Bruk Postman til å laste inn klientens PFX-fil i Innstillinger > Sertifikater.
- Velg Legg til sertifikat for å legge til klientsertifikatet.
- Konfigurer HTTP-hodet for x-adobesign-clientid:
Når den er konfigurert, sender du en POST forespørsel til webhook callback-nettadresse.
Du burde få 200 svar.
-
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:"" -out clientcert.crt -nokeys openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -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
- Abonner på spesifikke, nødvendige hendelser for å begrense antall HTTPS-forespørsler til serveren – desto mer spesifikk du kan gjøre webhooks, desto mindre volum må du bla gjennom.
- 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 – 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. Det anbefales å arbeide på en separat tråd eller asynkront ved hjelp av en kø for å sikre at du kan svare innen fem sekunder
- 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:
- Hvilke data vil du returnere i nyttelasten?
- Hvem får tilgang til denne informasjonen?
- 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» returneres i svaret når dette skjer for å informere klienten om at informasjonen med conditionalParameters har blitt 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.
