Ta ett exempel på JavaScript-kod för att hämta klient-ID, validera det och returnera det sedan i svarshuvudet
- Adobe Acrobat Sign-integreringar
- Nyheter
- Produktversioner och livscykel
- Acrobat Sign för Salesforce
- Installera paketet
- Konfigurera paketet
- Användarhandbok
- Aktivera digital autentisering
- Användarhandbok för utvecklare
- Handbok om avancerad anpassning
- Användarhandbok för fältmappning och mallar
- Användarhandbok för den mobila appen
- Flödesautomatiseringsguide
- Användarhandbok för Document Builder
- Konfigurera stora dokument
- Användarhandbok för uppgraderingar
- Versionsinformation
- Svar på vanliga frågor
- Felsökningsguide
- Ytterligare artiklar
- Acrobat Sign för Microsoft
- Acrobat Sign för Microsoft 365
- Acrobat Sign för Outlook
- Acrobat Sign för Word/PowerPoint
- Acrobat Sign för Teams
- Acrobat Sign för Microsoft PowerApps och Power Automate
- Acrobat Sign Connector för Microsoft Search
- Acrobat Sign för Microsoft Dynamics
- Acrobat Sign för Microsoft SharePoint
- Översikt
- SharePoint On-Prem: installationshandbok
- SharePoint On-Prem: användarhandbok för mallmappning
- SharePoint On-Prem: användarhandbok
- SharePoint On-Prem: versionsinformation
- SharePoint Online: installationshandbok
- SharePoint Online: användarhandbok för mallmappning
- SharePoint Online: användarhandbok
- SharePoint Online: användarhandbok för mappning av webbformulär
- SharePoint Online: versionsinformation
- Acrobat Sign för Microsoft 365
- Acrobat Sign för ServiceNow
- Acrobat Sign för HR ServiceNow
- Acrobat Sign för SAP SuccessFactors
- Acrobat Sign för Workday
- Acrobat Sign för NetSuite
- Acrobat Sign för SugarCRM
- Acrobat Sign för VeevaVault
- Acrobat Sign för Coupa BSM Suite
- Acrobat Sign för Zapier
- Utvecklingsdokumentation för Acrobat Sign
Översikt
En webhook är en användardefinierad HTTPS-begäran som utlöses när en prenumerationshändelse inträffar på källplatsen, (i detta fall Adobe Acrobat Sign).
En webhook är alltså en REST-tjänst som accepterar data eller en dataström.
Webhookar är avsedda för tjänst till tjänst -kommunikation i en PUSH-modell.
När en utlösande händelse inträffar, skapar Acrobat Sign en HTTPS-POST med JSON-text och skickar den till angiven URL.
Webhookar erbjuder flera fördelar jämfört med den tidigare återanropsmetoden, varav några är:
- Administratörer kan aktivera sina egna webbhookar utan att behöva involvera Acrobat Signs support för att lista återanrops-URL
- Webhookar är bättre när det gäller ”uppdaterade” data, effektivitet i kommunikation, och säkerhet. Ingen avsökning krävs
- Webhooks tillåter enkelt olika nivåer av omfattning (konto/grupp/användare/resurs).
- Webhookar är en modernare API-lösning, som gör det enklare att konfigurera moderna program
- Flera webbhookar kan konfigureras per omfattning (konto/grupp/användare/resurs) där återanrop måste vara unika
- Webhookar gör det möjligt att välja data som ska returneras, där återanrop är en ”allt eller inget”-lösning
- Metadata som medföljer en webhook kan konfigureras (grundläggande eller detaljerad)
- Webhooks är mycket enklare att skapa, redigera eller inaktivera efter behov eftersom användargränssnittet är helt inom administratörens kontroll.
Det här dokumentet är främst inriktat på webbhooks-gränssnittet i webbprogrammet Acrobat Sign (tidigare Adobe Sign).
Utvecklare som söker efter API-information hittar mer information här:
Så fungerar det
Administratörer måste först ha en webhook-tjänst som är redo att acceptera den inkommande push-tjänsten från Acrobat Sign. Det finns många alternativ i detta avseende, och så länge tjänsten kan acceptera POST- och GET-förfrågningar kommer denna webhook att lyckas.
När tjänsten är på plats, kan en Acrobat Sign-administratör skapa en ny webhook från Webhook-gränssnittet på kontomenyn på Acrobat Sign-webbplatsen.
Administratörer kan konfigurera webhooken för att utlösa händelser för avtal, webbformulär (Widget) och massutskick (MegaSign). Resursen Biblioteksmall (Biblioteksdokument) kan också konfigureras via API:et.
Omfattningen för en webhook kan inkludera hela kontot eller enskilda grupper via administratörsgränssnittet. API:et ger större justeringsmöjligheter genom val av användar- eller resursomfång.
Den typ av data som skickas till URL:en kan konfigureras och inkludera saker som avtalsinformation, deltagarinformation, dokumentinformation och så vidare.
När en webhook har konfigurerats och sparats, skickar Acrobat Sign ett nytt JSON-objekt till angiven URL varje gång prenumerationshändelsen utlöses. Ingen pågående manipulering av en webhook krävs om du inte vill ändra villkor för händelseutlösare eller JSON-nyttolasten.
Verifiering av avsikten med webhook-URL
Innan du registrerar en webhook kontrollerar Acrobat Sign om den webhook-URL som anges i registreringsbegäran har för avsikt att ta emot meddelanden eller inte. När Acrobat Sign får en ny begäran om registrering av en webhook gör den därför först en verifieringsbegäran till webhookens URL. Denna verifieringsbegäran är en HTTPS GET-begäran som skickas till webhook-URL:en. Denna begäran har ett anpassat HTTP-huvud X-AdobeSign-ClientId. Värdet i den här rubriken är inställt på klient-ID (program-ID) för det API-program som begär att en webhook ska skapas/registreras. För att kunna registrera en webhook, måste webhook-URL:en svara på denna verifieringsbegäran med en 2XX-svarskod och MÅSTE dessutom skicka tillbaka samma klient-ID-värde på något av följande två sätt:
- Antingen i en svarsrubrik med X-AdobeSign-ClientId. Det är samma rubrik som skickas i begäran och som sedan skickas tillbaka i svaret.
- Eller i JSON-svarstexten med nyckeln xAdobeSignClientId där värdet är samma klient-ID som skickades i begäran.
En webhook registreras endast vid framgångsrikt svar (2XX-svarskod) och valideringen av klient-ID i rubriken eller svarstexten. Syftet med denna verifieringsbegäran är att visa att webhook-URL:en verkligen vill ta emot meddelanden till avsedd URL. Om du av misstag har angett fel URL, kommer denna URL inte att svara korrekt på bekräftelsen av avsiktsbegäran och Acrobat Sign kommer inte att skicka några meddelanden till denna URL. Dessutom kan en webhook-URL även validera att den endast tar emot meddelanden via de webhookar som registreras av ett specifikt program. Detta kan göras genom att validera klient-ID för programmet som skickas i rubriken med X-AdobeSign-ClientId. Om en webhook-URL inte känner igen ett klient-ID, får den INTE svara med framgångsrik svarskod, och Acrobat Sign kommer att se till att denna URL inte registreras som en webhook.
Verifieringen av anrop till webhook-URL:en görs i följande situationer:
- Registrera webhook: om denna verifiering av ett anrop till en webhook-URL misslyckas, kommer denna webhook inte att skapas.
- Uppdatera webhook: INAKTIV till AKTIV: om denna verifiering av ett anrop till en webhook-URL misslyckas ändras inte tillståndet för denna webhook till AKTIV.
Så besvaras ett webhook-meddelande
Acrobat Sign utför en implicit avsiktsverifiering i varje begäran om webhook-meddelande som skickas till denna webhook-URL. Således innehåller varje HTTPS-begäran för webhook-avisering även det anpassade HTTP-huvudet som kallas X-AdobeSign-ClientId. Värdet på huvudet är klient-ID (program-ID) för programmet som skapade denna webhook. Vi kommer att betrakta webhook-meddelandet som framgångsrikt levererad om, och endast om, ett svar (2XX-svarskod) returneras och klient-ID skickas i HTTP-rubriken (X-AdobeSign-ClientId) eller via en JSON-svarstext med nyckeln xAdobeSignClientId och värdet som samma klient-ID. I annat fall försöker vi leverera meddelandet på nytt till webhook-URL:en tills alla nya försök har slutförts.
Som nämnts ovan, rubriken 'X-AdobeSign-ClientId' som ingår i varje aviseringsbegäran från Sign ska värdet på detta huvud (klient-ID) upprepas på något av följande två sätt:
1. HTTP-huvudet med X-AdobeSign-ClientId och värde som detta klient-id
|
---|
// Hämta klient-ID var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validera det if (clientid ==="BGBQIIE7H253K6") //Ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { //Returnera det i svarsrubriken response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // standardvärde } |
Ta ett exempel på PHP-kod för att hämta klient-ID, validera det och returnera det sedan i svarshuvudet |
---|
<?php // Hämta klient-ID $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validera det if($clientid == "BGBQIIE7H253K6") //Ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { //Returnera det i svarsrubriken header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // standardvärde } ?> |
2. JSON-svarstext med nyckel som xAdobeSignClientId och värde som samma klient-id
Ta ett exempel på JavaScript-kod för att hämta klient-ID, validera det och returnera det i svarstexten |
---|
// Hämta klient-ID var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validera det if (clientid ==="BGBQIIE7H253K6") //Ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { var responseBody = { "xAdobeSignClientId" : clientid // Returnera klient-ID i brödtexten }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; } |
Ta ett exempel på PHP-kod för att hämta klient-ID, validera det och returnera det i svarstexten |
---|
<?php // Hämta klient-ID $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validera det if($clientid == "BGBQIIE7H253K6") //Ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { //Returnera det i svarstexten header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // standardvärde } ?> |
Exempel på JSON-brödtext för svaret |
---|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
Förutsättningar
Du behöver:
- Ett Microsoft-konto med licens för att skapa Azure Functions-program
- Ett befintligt Azure-funktionsprogram kan du skapa med https://docs.microsoft.com/sv-se/azure/azure-functions/functions-create-first-azure-function
- Grundläggande kunskaper i Javascript, så att du kan förstå och skriva koden på valfritt språk
Steg för att skapa en utlösare för Azure-funktioner som fungerar som en Acrobat Sign-webhook
Så här skapar du en HTTP-utlösarfunktion för JavaScript:
1. Logga in via ditt Microsoft-konto https://portal.azure.com/
2. Öppna Azure Function-programmet som visas under fliken Function Apps.
Detta öppnar listan över Azure Function-program:
3. Välj programmet där du vill skapa den nya funktionen
4. Klicka på knappen Skapa (+) för att skapa en ny Azure-funktion
5. Välj Webhook + API som scenario och JavaScript som språk
6. Klicka på Skapa denna funktion
En ny funktion som kan hantera en inkommande API-begäran skapas.
Lägg till logik för att registrera en Acrobat Sign-webhook
Innan du registrerar en webhook kontrollerar Acrobat Sign att den webhook-URL som anges i registreringsbegäran verkligen har för avsikt att ta emot meddelanden eller inte. När en ny begäran om registrering av en webhook tas emot av Acrobat Sign gör den därför först en verifieringsbegäran till webhook-URL:en. Denna verifieringsbegäran är en HTTPS GET-begäran som skickas till webhook-URL med ett anpassat HTTP-huvud X-AdobeSign-ClientId. Värdet i detta huvud är inställt på klient-ID för programmet som begär att skapa/registrera denna webhook. För att kunna registrera en webhook svarar dess URL på denna verifieringsbegäran med en 2XX-svarskod OCH måste dessutom skicka tillbaka samma klient-ID-värde på något av följande två sätt.
Det finns två alternativ som du kan använda:
Alternativ 1: Skicka klient-ID i X-AdobeSign-ClientId som svarshuvud
Skicka X-AdobeSign-ClientId i svarshuvudet. Det är samma huvud som skickas i begäran och som sedan skickas tillbaka i svaret.
Ersätt filen Index.js med följande:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Verifiera att inkommande ClientID är äkta
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Standardvärdet är 200 */ // Alla 2XX-svar accepteras
body: "Avisering accepterad",
headers : {
'x-adobesign-clientid' : req.headers['x-adobesign-clientid']
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
Testa beteendet genom att testa förfrågan:
1. Klicka på knappen Test längst ned till höger
2. Testa prov-förfrågan
Även om svarshuvuden inte visas ovan, kan du observera det genom testa det med postman/DHC eller någon annan tjänst.
Alternativ 2: Skicka klient-ID i svarstexten med nyckeln xAdobeSignClientId
I JSON-svarstexten med nyckeln xAdobeSignClientId och dess värde är det samma klient-ID som skickas i begäran.
Ersätt filen Index.js med följande:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Verifiera att inkommande ClientID är äkta
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Standardvärdet är 200 */ // Alla 2XX-svar accepteras
body: {
'xAdobeSignClientId' : clientId
},
headers : {
'Content-Type' : 'application/json'
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
Testa beteendet genom att testa förfrågan
1. Klicka på knappen Test längst till höger
2. Testa prov-förfrågan
Observera också att samma beteende för clientID förväntas när webhook-URL tar emot POST-aviseringar.
Klar att använda
När du har verifierat beteendet, fungerar denna webhook-URL enligt Acrobat Sign-standarder. Du kan uppdatera den anpassade logiken efter dina behov.
Hämta funktions-URL
- Klicka på Hämta funktions-URL
Kopiera URL:en och använd den för att skapa webbhooks i Acrobat Sign.
Skapa AWS Lambda-funktion
Om du vill skapa en AWS Lambda-funktion, logga in på AWS Management Console och välj tjänsten AWS Lambda i listan med tjänster.
- Klicka på Skapa en Lambda-funktion med hjälp av alternativet “Skapa från grunden”
- På sidan Konfigurera funktion, ange funktionsnamn “lambdaWebhooks” och välj Node.js 4.3 som körning
- För Roll välj en befintlig roll eller skapa en ny roll från mallar
- Om du har valt Skapa ny roll från mallar, ange ett rollnamn (t.ex. roll-lamda) och välj Enkla Microservices-behörigheter från listan över Policymallar
- Klicka på knappen Skapa funktion
- På den nya sidan AWS lamda-funktion välj "Redigera kod inline" som "Typ av kodinmatning", behåll index.handler som Handler.
- Lägg till logik för att registrera Acrobat Sign Webhook
Innan du registrerar en webhook kontrollerar Acrobat Sign att den webhook-URL som anges i registreringsbegäran verkligen har för avsikt att ta emot meddelanden eller inte. När en ny begäran om registrering av en webhook tas emot av Acrobat Sign gör den därför först en verifieringsbegäran till webhook-URL:en. Denna verifieringsbegäran är en HTTPS GET-begäran som skickas till webhook-URL med ett anpassat HTTP-huvud X-AdobeSign-ClientId. Värdet i detta huvud är inställt på klient-ID för programmet som begär att skapa/registrera denna webhook. För att kunna registrera en webhook svarar dess URL på denna verifieringsbegäran med en 2XX-svarskod OCH kan dessutom skicka tillbaka samma klient-ID-värde på något av följande två sätt. Observera även att samma beteende för clientID förväntas när en webhook-URL tar emot POST-aviseringar.
Gör något av följande:
Fall 1: Skicka klient-ID i X-AdobeSign-ClientId som svarshuvud
- Skicka X-AdobeSign-ClientId i svarshuvudet. Det är samma huvud som skickas i begäran och som sedan skickas tillbaka i svaret.
Kodfragment
Ersätt det automatiskt genererade kodfragmentet med följande kod i filen index.js:
- Skicka X-AdobeSign-ClientId i svarshuvudet. Det är samma huvud som skickas i begäran och som sedan skickas tillbaka i svaret.
Exempelnodens JS-kod för att hämta klient-ID, validera den och returnera den sedan i svarshuvudet |
---|
exports.handler = function index(event, context, callback) { // Hämta klient-ID var clientid = event.headers['X-AdobeSign-ClientId'];
//Validera det if (clientid =="BGBQIIE7H253K6") //ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } } |
Fall 2: Skicka klient-ID i svarstexten med nyckel xAdobeSignClientId
I JSON-svarstexten med nyckel för xAdobeSignClientId och dess värde är samma klient-ID som skickas i begäran.
Kodfragment
Ersätt filen Index.js med följande:
Exempelnodens JS-kod för att hämta klient-ID, validera den och returnera den sedan i svarshuvudet |
---|
exports.handler = function index(event, context, callback) { // Hämta klient-ID var clientid = event.headers['X-AdobeSign-ClientId'];
//Validera det if (clientid =="BGBQIIE7H253K6") //Ersätt 'BGBQIIE7H253K6' med klient-ID för programmet som denna webhook skapas med { var responseBody = { xAdobeSignClientId : clientid };
var response = { statusCode: 200, body: JSON.stringify(responseBody) };
callback(null,response); } else { callback("Opps!! illegitimate call"); } } |
- Spara funktionen. Lambda-funktionen skapas och vi är nästan redo att använda den i en webhook i realtid.
Konfigurera AWS API Gateway
För att göra denna Lambda offentligt tillgänglig via en HTTP-metod måste vi konfigurera AWS API Gateway med hjälp av vår funktion (skapad ovan) som serverdel för detta API.
I AWS Management Console väljer du API Gateway från AWS-tjänsten och klicka på knappen Skapa API
- På sidan Skapa nytt API, välj Nytt API och ange webhooks som API-namn.
- Klicka på knappen Skapa API
- Välj Åtgärder i listrutan och välj alternativet Skapa resurs
- Kontrollera alternativet Konfigurera som proxyresurs och ange validera som Resursnamn och {proxy+} i Resurssökväg
- Lämna alternativet Aktivera API Gateway-CORS avmarkerat och klicka på knappen Skapa resurs
- Behåll Lambda Funktionsproxy markerad som Integrationstyp och välj det område där du har skapat lambdafunktionen i listrutan Lambdaregionen (förmodligen är det samma region där du skapar API Gateway).
- Ange validera som Lambda-funktion och klicka på knappen Spara
- I dialogrutan Lägg till behörighet till Lambda-funktion, välj OK
Om alla steg ovan utförs korrekt ser du ungefär det här:
Distribuera API
Nästa steg är att distribuera detta API så att det blir klart att användas.
- I listrutan Åtgärder, välj Distribuera API
- Välj [New Stage] i Distributionssteg och ange prod (eller något annat som du vill identifiera detta steg med) i Stegnamn
- Klicka på knappen Distribuera
API är nu klart att användas och du hittar anrops-URL i den blå rutan som visas nedan:
Notera denna URL eftersom den måste anges som webhook-URL i realtid.
Klar att använda
Det är gjort. Använd ovanstående URL ovan med “/{nodeJSfunctionName}” som läggs till som webhook-url i POST /webhooks API-begäran. När du har verifierat beteendet fungerar denna webhook-URL enligt
Acrobat Sign-standarder. Du kan uppdatera/lägga till anpassad logik efter dina behov.
Konfigurationsalternativ
Konfigurering av webhook kräver att fem element definieras:
- Namn – ett intuitivt namn som andra administratörer lätt kan förstå föreslås.
- Omfång – hur brett nätet är som används av en webhook? Kontot och gruppen är tillgängliga i gränssnittet.
- API:et stöder omfattningar för konto, grupper, användare och resurser.
- Endast ett omfång per webhook kan definieras.
- URL – mål-URL:en som Acrobat Sign skickade JSON-nyttolasten till.
- Händelser – utlösaren som gör att Acrobat Sign skapar JSON och skickar den till avsedd URL.
- Varje händelse skapar en egen nyttolast som är relevant för den utlösande händelsen.
- Flera Händelser kan inkluderas i en webhook.
- Meddelandeparametrar – meddelandeparametrarna identifierar de delar av Händelsens JSON-nyttolast, så att du kan välja endast de avsnitt som är viktiga för denna webhook i Händelsen (och därmed minska onödig data som skickas till URL:en).
När en webhook är helt definierad, klicka på Spara, och denna nya webhook börjar direkt reagera på utlösande händelser.
Konfigurera webhook-URL:en för att svara på begäranden om webhook-verifiering och webhook-meddelanden enligt verifieringsprotokoll ovan. Det klient-ID (program-ID) som skickas till webhooks som skapas från webbapplikationen Acrobat Sign, är – UB7E5BXCXY
Omfång
- Konto: Alla prenumerationshändelser som inträffar på kontot utlöser push-åtgärden.
- Kontoadministratörer har behörighet att se alla webbhookar definierade för kontot och alla grupper i kontot.
- Grupp: Alla prenumerationshändelser som inträffar i gruppen utlöser push-åtgärden. OBS! Webbhookar med gruppomfång finns bara för den gruppen.
- Gruppadministratörer kan bara se webhookar som är dedikerade till deras grupp. De kan inte se webbhooks på kontonivå eller webhooks som är bundna till andra grupper.
- Konton som har Användare i flera grupper aktiverat, ser alternativet att ange gruppen som omfånget ska tillämpas på.
- Användarkonto: Alla prenumerationshändelser för ett användarkonto utlöser push-åtgärd. Webhooks på användarnivå kan bara skapas via API.
- Webhook på resursnivå: Detta skapas för en specifik resurs. Händelser som är specifika för denna resurs överförs till aktuell webhook-URL. Webhookar på resursnivå kan bara skapas via API.
URL
En webhook-URL är en server som lyssnar efter inkommande HTTPS-POST-aviseringar som utlöses när händelser inträffar.
Du behöver denna URL för att prenumerera på webhook för händelser.
- Klienten måste innehålla en HTTPS URL som Acrobat Sign kan skicka POST-aviseringar till. Denna URL måste vara tillgänglig på offentligt Internet.
- Till exempel kommer 127.0.0.1 och localhost-URI:er inte att fungera.
- URL-slutpunkten måste lyssna på port 443 eller 8443 (bestäms av kunden när återanrops-URL:en definieras).
- Se till att webhooken stöder POST-förfrågningar för inkommande händelseaviseringar och GET-förfrågningar för verifieringsförfrågan.
- Webbadressen bör inte blockeras av en brandvägg.
Nedan visas de händelser som kan utlösa en push till webhook-URL:en, grupperade efter objekt och listade i den ordning som finns i användargränssnittet.
Värdet till vänster är det som visas i användargränssnittet i Acrobat Sign. Värdet till höger är webhookens namn i API:et.
Fullständig information om webbhookarna och deras nyttolaster finns i Utvecklarhandbok för Acrobat Sign.
Avtal:
Användargränssnittelement | Webhooknamn |
Avtal med alla händelser | AGREEMENT_ALL |
Avtalet har skapats | AGREEMENT_CREATED |
Avtal skickat | AGREEMENT_ACTION_REQUESTED |
Avtalsdeltagaren har slutfört | AGREEMENT_ACTION_COMPLETED |
Arbetsflöde för avtal slutfört | AGREEMENT_WORKFLOW_COMPLETED |
Avtalet har upphört att gälla | AGREEMENT_EXPIRED |
Avtalet har tagits bort | AGREEMENT_DOCUMENTS_DELETED |
Avtalet har avbrutits | AGREEMENT_RECALLED |
Avtalet har avvisats | AGREEMENT_REJECTED |
Avtalet har delats | AGREEMENT_SHARED |
Avtalet har delegerats | AGREEMENT_ACTION_DELEGATED |
Avtalsdeltagare har ersatts | AGREEMENT_ACTION_REPLACED_SIGNER |
Avtal har ändrats | AGREEMENT_MODIFIED |
Ändring av avtal har bekräftats | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
Avtalets e-postmeddelande har lästs | AGREEMENT_EMAIL_VIEWED |
Avtalets e-postmeddelande studsade | AGREEMENT_EMAIL_BOUNCED |
Avtalet kunde inte skapas | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
Avtal synkroniserades efter offline-händelse | AGREEMENT_OFFLINE_SYNC |
Avtalet har överförts av avsändaren | AGREEMENT_UPLOADED_BY_SENDER |
Avtalet placerat i valvet | AGREEMENT_VAULTED |
Avtalsdeltagarens sociala ID har autentiserats | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
Avtalsdeltagaren är KBA-autentiserad | AGREEMENT_KBA_AUTHENTICATED |
Avtalspåminnelse har skickats | AGREEMENT_REMINDER_SENT |
Namnet på avtalets signerare har ändrats av signeraren | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
Avtalswebbhookar är endast tillgängliga via API | |
Ej tillämpligt | AGREEMENT_EXPIRATION_UPDATED |
Ej tillämpligt |
AGREEMENT_READY_TO_NOTARIZE |
Ej tillämpligt |
AGREEMENT_READY_TO_VAULT |
Massutskick:
Användargränssnittelement | Webhooknamn |
Massutskicka alla händelser | MEGASIGN_ALL |
Massutskick skapade |
MEGASIGN_CREATED |
Massutskick delade |
MEGASIGN_SHARED |
Massutskick återkallat |
MEGASIGN_RECALLED |
Webbformulär:
Användargränssnittelement | Webhooknamn |
Alla händelser för webbformulär | WIDGET_ALL |
Webbformuläret har skapats |
WIDGET_CREATED |
Webbformuläret har aktiverats |
WIDGET_ENABLED |
Webbformuläret har inaktiverats |
WIDGET_DISABLED |
Webbformuläret har ändrats |
WIDGET_MODIFIED |
Webbformuläret har delats |
WIDGET_SHARED |
Det gick inte att skapa ett webbformulär |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Biblioteksmallar (endast API):
Användargränssnittelement | Webhooknamn |
Ej tillämpligt | LIBRARY_DOCUMENT_ALL |
Ej tillämpligt | LIBRARY_DOCUMENT_CREATED |
Ej tillämpligt | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
Ej tillämpligt | LIBRARY_DOCUMENT_MODIFIED |
Meddelandeparametrar
Med meddelandeparametrar kan du anpassa JSON-nyttolasten till specifika element i händelsen.
I en händelse av Avtalsdeltagare ersatt kanske du bara vill ha Avtalsinformation och Deltagarinformation och utelämna Dokumentinformation, och minska den totala storleken på den JSON som skickas i webhook-URL:en.
- Avtal
- Avtalsinformation – detaljerad avtalsinformation baserad på avtalets status vid tidpunkten för den utlösande händelsen.
- Dokumentinformation för avtal – inkluderar all dokumentinformation som genereras som ett resultat av händelsen.
- Information om avtalsdeltagare – inkluderar all deltagarinformation som ett resultat av händelsen.
- Signerat avtalsdokument – tillhandahåller den signerade PDF-filen.
- Gäller händelserna Avtalsarbetsflödet har slutförts och Alla avtal.
- Massutskick
- Information om massutskick – detaljerad information om det Massutskickobjekt som utlöste händelsen.
- Webbformulär
- Widgetinformation – detaljerad information om webbformuläret som utlöste händelsen.
- Information om Widget-dokument – dokumentinformationen som är associerad med webbformuläret.
- Widget-deltagarinformation – information om definierade deltagare i webbformuläret.
Tvåvägs SSL-autentisering
Tvåvägs-SSL, ofta kallad Client-Side SSL eller ömsesidig TLS, är ett SSL-läge där både servern och klienten (webbläsaren) presenterar certifikat för att identifiera sig själva.
Kontoadministratörer kan konfigurera ett klientcertifikat på sidan Säkerhetsinställningar.
Acrobat Sign verifierar SSL-certifikat vid leverans av nyttolaster till webhook-URL. Webhookar som misslyckas med SSL-certifikatverifiering kan inte leverera JSON-nyttolast.
Använd tvåvägs SSL för att autentisera klienten (Acrobat Sign) och lyssningstjänsten för att säkerställa att endast Acrobat Sign kan nå webhook-URL:en.
Om en webhook skapades av ett Partnerprogram kommer denna webhook att använda ett klientcertifikat (om tillgängligt) från partnerprogrammets konto för att identifiera sig själv när den skickar webhook-meddelanden.
Nedan visas de vanligaste frågorna för både verifiering av webbserver och verifiering av klientcertifikat.
Webbserververifiering
När en webhook registreras verifierar Acrobat Sign webhookserverns URL.
Kunder kommer inte att kunna registrera webhooken om anslutningen till webhookens återanrops-URL inte kan slutföras från Acrobat Sign.
Nej.
Återanrops-URL för webhook kan bara vara HTTPS på port 443 eller 8443.
Acrobat Sign blockerar utgående HTTPS-trafik till alla andra portar.
Ett bra sätt att verifiera servercertifikatet är att använda Diagnostikverktyget för DigiCert® SSL-installation.
Ange endast värdnamn, t.ex.: www.digicert.com
Vanliga problem är:
- Problem: Använda en otillförlitlig certifikatutfärdare eller ett självsignerat certifikat
Åtgärd: använd ett offentligt utfärdat SSL-certifikat för webhookens återanropsserver.
- Problem: servern skickar inte det mellanliggande certifikatet
Åtgärd: installera de mellanliggande certifikaten på återanropsservern för webhook.
Se https://www.digicert.com/kb/ssl-certificate-installation.htm för detaljerad information.
Verifiering av klientcertifikat
För att konfigurera en tvåvägs-SSL för en webhook, kräver vi att administratören överför en .p12 (eller .pfx-fil) som innehåller den privata nyckeln. Filen lagras säkert på kundkontot och administratören har fullständig kontroll över att ta bort den när som helst.
I en tvåvägs webhook-konfiguration är, Acrobat Sign uppringaren/klienten och behöver den privata nyckeln för att bevisa att samtalet görs av Acrobat Sign för kundkontot.
-
Kontrollera att tvåvägs-SSL är aktiverat
Tvåvägs-SSL måste aktiveras på återanropsservern för webhook.
Anslut till återanrops-länken för webhook via valfri webbläsare. Du borde få:
400 Felaktig begäran Inget nödvändigt SSL-certifikat skickades
Det innebär att servern förväntar sig att klienten ska skicka klientcertifikat (dvs.: tvåvägs-SSL har aktiverats för servern).
Om du inte ser ovanstående meddelande är tvåvägs-SSL inte aktiverat.
Obs!Du kan använda Postman och göra en POST-begäran till återanrops-länken för webhook. Du borde få ett liknande resultat.
-
Klientautentiseringsuppgifterna kan antingen vara ett självsignerat certifikat eller CA- utfärdat certifikat. Det måste dock minst uppfylla följande X.509 v3-tillägg:
X.509 v3-tillägg
Värde
ExtendedKeyUsage
clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
Klientcertifikatet måste vara en PKCS12-fil med filnamnstillägget .p12 eller .pfx och det måste innehålla både klientcertifikatet (så att servern kan verifiera klientens identitet) och klientens privata nyckel (så att klienten kan signera meddelanden digitalt för servern för att verifiera under SSL-handskakningen).
Använd kommandot openssl för att verifiera p12-filen (pfx):
openssl pkcs12 -info -in outfile.p12
Lösenfrasen för den privata nyckeln ska begäras. Utdata bör innehålla både certifikat och en krypterad privat nyckel 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-----
Certifikaten bör åtminstone innehålla slutanvändarcertifikatet och de mellanliggande certifikaten. Helst ska det även innehålla rot-CA-certifikatet.
Varning:Se till att .p12- eller .pfx-filen är lösenordsskyddad.
-
Skapa ett självsignerat klientcertifikat (valfritt)
Klientcertifikat kan antingen utfärdas av en certifikatutfärdare eller vara självsignerade, beroende på dina behov.
För att generera ett självsignerat klientcertifikat, använd följande openssl -kommando:
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Viktigt:Håll de resulterande filerna hemliga eftersom de är dina självsignerade CA-certifikat.
Generera sedan klient-.p12-filen:
- Generera en privat nyckel för SSL-klienten:
openssl genrsa -out client.key 2048
- Använd klientens privata nyckel för att generera en certifikatbegäran:
openssl req -new -key client.key -out client.req
- Utfärda klientcertifikatet med hjälp av certifikatbegäran och certifikatutfärdarens certifikat/nyckel:
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Konvertera klientcertifikatet och den privata nyckeln till formatet pkcs#12 för användning i webbläsare:
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Ta bort klientens privata nyckel, klientcertifikatet och klientbegärandefiler eftersom pkcs12 har allt du behöver.
rm client.key client.cer client.req
- Generera en privat nyckel för SSL-klienten:
-
- Använd Postman för att läsa in klientens PFX-fil i Inställningar > Certifikat.
- Välj Lägg till certifikat för att lägga till klientcertifikatet.
- Konfigurera HTTP-huvudet för x-adobesign-clientid:
När konfigurationen är klar skickar du en POST-begäran till återanrops-länken för webhook.
Du bör få ett 200 -svar.
-
Varför avvisar Acrobat Sign min PFX-fil även efter att jag har verifierat den med Postman?
Om du har följt ovanstående procedur för pfx-filverifiering och Acrobat Sign fortfarande avvisar pfx-filen är det troligt att filen genererades av ett Microsoft-verktyg som kan producera en PKCS12-fil som inte är standard.
Använd i sådana fall nedanstående openssl-kommandon för att extrahera certifikaten och den privata nyckeln från pfx-filen och generera sedan en korrekt formaterad PKCS12-fil:
// Extrahera certifikat och privat nyckel från 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 // Skapa ny PKCS12-fil openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Så här aktiverar och inaktiverar du
Åtkomst till funktionen Webhooks är aktiverad som standard för konton med företagsplaner.
Administratörer på gruppnivå kan endast skapa/styra webhooks som fungerar inom gruppen.
Åtkomst till sidan Webhooks finns i den vänstra listen på Admininistrationsmenyn: Konto > Webhooks
Aktivera en webhook
När en webhook skapas första gången, skapas den med en Aktiv status.
På sidan webhooks i Acrobat Sign visas aktiva webhooks som standard.
Så här aktiverar du en inaktiv webhook:
- Klicka på ikonen Alternativ (tre vågräta linjer) till höger om rubrikraden webhooks och välj Visa alla webbhooks
- Klicka en gång på en inaktiv webhook för att markera den
- Detta visar alternativen för aktuell webhook precis under rubrikraden
- Klicka på Aktivera
En aktiv webhook börjar skicka data till mål-URL så snart nästa händelse utlöses.
Inaktivera en webhook
För att inaktivera en webhook behöver du
- Gå till sidan Webhooks
- Klicka på den webhook du vill inaktivera
- Välj Inaktivera från menyalternativen under rubrikraden
- När den är inaktiverad visas satus för webhook som Inaktiv
Visa eller redigera en webhook
Webhooks kan redigeras och sparas när som helst. När en ny konfiguration sparas träder ändringen i kraft omedelbart.
Endast Händelser och Meddelandeparametrar kan redigeras.
Om Namn, Omfång eller URL måste ändras, måste en ny webhook skapas.
Så här redigerar du parametrar för en webhook:
- Gå till sidan Webhooks
- Klicka på den webhook du vill redigera
- Klicka på alternativet Visa/redigera under rubrikraden
- Tillämpa eventuella ändringar och klicka på Spara
Ta bort en webhook
En webhook kan när som helst tas bort.
Om du tar bort en webhook förstörs den i systemet, så det går inte att återställa en borttagen webhook.
Webhooks behöver inte inaktiveras först.
Så här tar du bort en webhook:
- Gå till Webhooks
- Välj den webhook som du vill ta bort genom att klicka på den
- Klicka på alternativet Radera under rubrikraden
- En kontroll visas för att säkerställa att du vill ta bort en webhook. klicka på OK
Bästa praxis
- Prenumerera på specifika händelser som behövs för att begränsa antalet HTTPS-begäranden till servern – ju mer specifika du kan göra dina webhookar, desto mindre volym behöver du gå igenom.
- Vara dublettresistent – om du har fler än ett program som delar samma webhook-URL och samma användare mappas till varje program, skickas samma händelse till din webhook flera gånger (en gång per program). I vissa fall kan din webhook ta emot dubbletthändelser. Webhook-applikationen bör vara tolerant mot detta och dedupera med händelse-ID.
- Besvara alltid webhookar snabbt – appen har bara tio sekunder på sig att besvara webhook-förfrågningar. För verifieringsbegäran är detta sällan ett problem eftersom din app inte behöver göra något egentligt arbete för att svara. För aviseringsförfrågningar kommer dock appen vanligtvis att göra något som tar tid vid svar på begäran. Vi rekommenderar att du arbetar på en separat tråd eller asynkront med en kö så att du säkert kan svara inom fem sekunder
- Hantera samtidighet – när en användare gör ett antal ändringar i snabb följd får din app troligen flera meddelanden för samma användare vid ungefär samma tidpunkt. Om du inte är försiktig med hur du hanterar samtidig användning kan det sluta med att programmet bearbetar samma ändringar för samma användare flera gånger. För att dra nytta av Acrobat Sign webhooks måste du ha en tydlig förståelse för användningen av informationen. Var noga med att ställa frågor som:
- Vilka data vill du returnera i nyttolasten?
- Vem kommer att få tillgång till denna information?
- Vilka beslut eller rapporter kommer att genereras?
- Rekommendationer för att ta emot signerade dokument – det finns flera faktorer att ta hänsyn till när du avgör hur du tar emot en signerad PDF-fil från Acrobat Sign i dokumenthanteringssystemet.
Även om det är helt acceptabelt att bara välja alternativet Signerat avtalsdokument när du skapar en webhook, kan du använda API för Acrobat Sign för att hämta dokumenten när en utlösande händelse (till exempel avtalsstatus slutförd) tas emot.
Saker att tänka på ...
JSON storleksbegränsning
JSON nyttolast är begränsad till 10 MB.
Om en händelse genererar en större nyttolast utlöses en webhook men attribut för villkorlig parameter, om sådana finns i begäran, tas bort för att minska nyttolastens storlek.
ConditionalParametersTrimmed returneras i svaret när detta händer för att informera klientorganisationen om att informationen conditionalParameters har tagits bort.
“conditionalParametersTrimmed” är ett matris-objekt som innehåller information om de nycklar som har trimmats.
Trunkeringen sker i följande ordning:
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
Signerade dokument trunkeras först, följt av deltagarinformation, dokumentinformation och slutligen detaljerad information.
Detta kan till exempel inträffa vid en händelse för avtalsslutförande om den inkluderar ett signerat dokument (base 64-kodad) eller för ett avtal med flera formulärfält
Webhook-meddelanden
Acrobat Sign webhooks levererar meddelanden som gäller för alla deltagare i ett avtal om det finns en webhook som är konfigurerad för den användaren, deras grupp eller deras konto.
Avtalshändelser behandlas på ett sådant sätt att om det finns en webhook konfigurerad för den tillämpliga deltagaren i den händelsen, skickas ett meddelande till aktuell webhook-URL. Med andra ord aktiveras webhooks för händelser i alla tillämpliga avtal, även utanför den grupp eller det konto för vilken aktuell webhook är konfigurerad.
Meddelanden levereras endast för de händelser som deltagaren är involverad i. T.ex. Avsändare av ett avtal får nästan varje meddelande, medan Mottagare endast får meddelanden från början av deras deltagande i avtalet, och endast för de händelser som de är inblandade i.
Webhook-meddelanden följer den aktuella autentiserings- och synlighetsmodellen för själva Acrobat Sign, vilket innebär att användare endast har åtkomst till avtalet när användarens deltagande i ett avtal har påbörjats.
Avsändaren skickar ett avtal för signering till tre signerare.
- Det finns en kontonivå WebhookX som konfigurerats för avsändarkontot.
- Signerare1 är medlem av samma konto som avsändaren men i en annan grupp, och det finns en WehbhookY som konfigurerats för den gruppen.
- Signerare2 är medlem i ett annat konto, och det finns en kontonivå WebhookZ som konfigurerats för kontot Signerare2.
- Signerare3 är medlem i samma konto som en avsändare.
Avsändaren skickar ett avtal: WebhookX utlöser för “Avtalet har skapats” och “Avtal skickat” medan WebhookY utlöser för “Avtal skickat”.
Signerare1 signerar: WebhookX utlöser på “Avtalsdeltagare slutförd” och “Avtal skickat”, WebhookY utlöser på “Avtalsdeltagaren har slutfört” och WebhookZ utlöser för “Avtal skickat”.
Signerare2 signerar: WebhookX utlöser på “Avtalsdeltagare slutförd” och “Avtal skickat”, medan WebhookZ skickar ett meddelande för “Avtalsdeltagaren har slutfört”.
Signerare3 signerar: WebhookX utlöser för “Avtalsdeltagare har slutfört” och “Avtalsarbetsflöde slutfört”, WebhookY utlöser för “Avtalsarbetsflöde slutfört”, och WebhookZ utlösare för “Avtalsarbetsflöde slutfört”.
Försök igen när lyssningstjänsten är nere
Om aktuell mål-URL för en webhook av någon anledning inte fungerar, ställer Acrobat Sign JSON-servern i kö och försöker sedan köra push-funktionen på nytt i en progressiv cykel under 72 timmar.
De ej levererade händelserna sparas i en kö för återförsök och under de kommande 72 timmarna görs allt för att leverera meddelandena i den ordning de inträffade.
Strategin för att försöka leverera meddelanden på nytt är en fördubbling av tiden mellan försöken, med ett intervall som startar på 1 minut och ökar till var 12:e timme, vilket resulterar i 15 försök under 72 timmar.
Om webhook-mottagaren inte svarar inom 72 timmar och inga meddelanden har skickats under de senaste sju dagarna kommer aktuell webhook att bli inaktiverad. Inga meddelanden skickas till denna URL förrän denna webhook är aktiverad igen.
Alla meddelanden mellan den tidpunkt då aktuell webhook inaktiverades och sedan aktiverades igen kommer att förloras.