Översikt över Acrobat Sign Webhook

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

Innan du konfigurerar webhookar, se till att ditt nätverk accepterar de IP-intervall som krävs för funktionalitet.

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.

Förutsättningar

Du måste tillåta IP-intervallen för webhookar via din nätverkssäkerhet för att tjänsten ska fungera. 

Den äldre tjänsten för återanrops-URL i REST v5 använder samma IP-intervall som webhook-tjänsten.

Så här används 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.

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 webhookar som fungerar inom gruppen.

Åtkomst till sidan Webhookar finns i den vänstra listen i Admininistrationsmenyn.

Samtidighetsbaserad hastighetsbegränsning

Skapande och aviseringshändelser av webhook (och återuppringning) är begränsade i antalet samtidiga meddelanden som aktivt levereras till kunden från Acrobat Sign-systemet. Denna gräns gäller för kontot, för att inkludera alla grupper inom kontot.
Denna typ av hastighetsbegränsning förhindrar ett dåligt utformat konto från att konsumera en oproportionerligt stor mängd resurser på servrar, vilket påverkar alla andra kunder i den servermiljön negativt.

Antalet samtidiga händelser per konto har beräknats för att säkerställa att konton med välordnade webhooks kommer att få sina meddelanden på kortast möjliga tid och bör sällan stöta på en situation där meddelanden blir försenade på grund av för många förfrågningar. Nuvarande tröskelvärden är:

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

Via Acrobat Sign-webhookar skickas meddelanden till avtalets avsändare och eventuella webhookar som konfigurerats inom grupp som avtalet skickats från. Webbhooks med kontoomfattning mottar samtliga händelser.

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.