Oversigt over Acrobat Sign-webhook

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.

Før du konfigurerer webhooks, skal du sørge for, at dit netværk accepterer de IP-intervaller, der kræves til funktionalitet.

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.

Forudsætninger

Du skal lade IP-intervallerne for webhooks passere din netværkssikkerhed for at tjenesten kan fungere. 

Den ældre tilbagekaldelses-URL-tjeneste i REST v5 bruger de samme IP-intervaller som webhook-tjenesten.

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.

Aktivering og deaktivering

Adgang til Webhooks-funktionen er som standard aktiveret for Enterprise-konti.

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.

Samtidighedsbaseret satsbegrænsning

Oprettelses- og notifikationshændelser for webhook (og tilbagekaldelse) er begrænset i antallet af samtidige notifikationer, der aktivt leveres til kunden fra Acrobat Sign-systemet.  Denne grænse gælder for kontoen, så den inkluderer alle grupper på kontoen.
Denne type satsbegrænsning forhindrer en dårligt designet konto i at bruge en for stor mængde serverressourcer og har dermed en negativ effekt på alle andre kunder i det pågældende servermiljø.

Antallet af samtidige hændelser pr. konto er blevet beregnet for at sikre, at konti med velfungerende webhooks modtager deres meddelelser hurtigst muligt og sjældent oplever, at meddelelser forsinkes på grund af for mange anmodninger. De nuværende tærskler er:

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 notifikationer til afsenderen af aftalen og enhver webhook, der er konfigureret inden for den gruppe, som aftalen blev sendt fra. Konto-webhooks modtager alle hændelser.

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.