Eksempel Javascript-kode til at hente klient-id, validere det, og derefter returnere det i svaroverskrift
Sidst opdateret den
4. jan. 2024
|
Gælder også for Adobe Acrobat Sign
- Adobe Acrobat Sign-integrationer
- Nyheder
- Produktversioner og livscyklus
- Acrobat Sign til Salesforce
- Installér pakken
- Konfigurer pakken
- Brugerhåndbog
- Aktivér Digital godkendelse
- Udviklervejledning
- Vejledning i avanceret tilpasning
- Vejledning i felttilknytning og skabeloner
- Brugerhåndbog til mobilapp
- Flows Automation-vejledning
- Document Builder-vejledning
- Konfigurer store dokumenter
- Opgraderingsvejledning
- Produktbemærkninger
- Ofte stillede spørgsmål
- Fejlfindingsvejledning
- Flere artikler
- Acrobat Sign til Microsoft
- Acrobat Sign til Microsoft 365
- Acrobat Sign til Outlook
- Acrobat Sign til Word/PowerPoint
- Acrobat Sign til Teams
- Acrobat Sign til Microsoft PowerApps og Power Automate
- Acrobat Sign Connector til Microsoft Search
- Acrobat Sign til Microsoft Dynamics
- Acrobat Sign til Microsoft SharePoint
- Oversigt
- SharePoint On-Prem: Installationsvejledning
- SharePoint On-Prem: Vejledning i skabelontilknytning
- SharePoint On-Prem: Brugervejledning
- SharePoint On-Prem: Produktbemærkninger
- SharePoint Online: Installationsvejledning
- SharePoint Online: Vejledning i skabelontilknytning
- SharePoint Online: Brugervejledning
- SharePoint Online: Vejledning i tilknytning af webformularer
- SharePoint Online: Produktbemærkninger
- Acrobat Sign til Microsoft 365
- Acrobat Sign til ServiceNow
- Acrobat Sign til HR ServiceNow
- Acrobat Sign til SAP SuccessFactors
- Acrobat Sign til Workday
- Acrobat Sign til NetSuite
- Acrobat Sign til SugarCRM
- Acrobat Sign til VeevaVault
- Acrobat Sign til Coupa BSM Suite
- Acrobat Sign til Zapier
- Acrobat Sign-udviklerdokumentation
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
|
|
|---|
|
// 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:
- En Microsoft-konto med licens til at oprette Azure Functions-programmer
- Du kan oprette et eksisterende Azur Function-program via https://docs.microsoft.com/da-dk/azure/azure-functions/functions-create-first-azure-function
- 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:
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:
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:
- Send X-AdobeSign-ClientId i svaroverskriften. Det er den samme overskrift, der sendes i anmodningen og gentages i svaret.
|
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:
|
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 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
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.
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
- Widgetoplysninger – 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.
- 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.
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.
-
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.
-
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.
Advarsel:Kontrollér, at .p12- eller .pfx-filen er beskyttet med adgangssætning.
-
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:
- Generér en privat nøgle til SSL-klienten:
openssl genrsa -out client.key 2048
- Brug klientens private nøgle til at generere en certificeringsanmodning:
openssl req -new -key client.key -out client.req
- 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
- 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
- Fjern klientens private nøgle, klientcertifikat og klientanmodningsfiler, da pkcs12 har alt, hvad du behøver.
rm client.key client.cer client.req
- Generér en privat nøgle til SSL-klienten:
-
- Brug Postman til at indlæse klientens PFX-fil i Indstillinger > Certifikater.
- Vælg Tilføj certifikat for at tilføje klientcertifikatet.
- Konfigurer HTTP-sidehovedet for x-adobesign-clientid:
Når det er konfigureret, skal du sende en POST anmodning til webhook callback URL.
Du burde få et svar på 200.
-
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:"" -out clientcert.crt -nokeys openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -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 oplysningerne conditionalParameters 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.
