Brukerveiledning Avbryt

 Oversikt over Acrobat Sign Webhook

 

Veiledning for Adobe Acrobat Sign

Nyheter

Kom i gang

Administrer

Sende, signere og behandle avtaler

Avanserte avtalefunksjoner og arbeidsflyter

Integrere med andre produkter

Acrobat Sign-utvikler

Kundestøtte og feilsøking

Overblikk

En webhook er en brukerdefinert HTTPS-forespørsel som utløses når en bestemt hendelse oppstår på kildeområdet (Adobe Acrobat Sign i dette tilfellet).

En webhook er ikke mer enn en REST-tjeneste som aksepterer data eller en datastrøm.

Webhooks er ment for service-til-service-kommunikasjon i en PUSH-modell.

Når en abonnert hendelse oppstår, konstruerer Acrobat Sign en HTTPS POST med en JSON-tekst og leverer den til den angitte nettadressen.

Før du konfigurerer webhooks, må du kontrollere at nettverket ditt godtar IP-områdene som kreves for funksjonaliteten.

 

Webhooks tilbyr flere fordeler i forhold til den forrige tilbakekallingsmetoden. Noen av disse er:

  • Administratorer kan aktivere sine egne webhooks uten å måtte involvere Acrobat Sign-støtte for å vise nettadressen for tilbakekall
  • Webhooks er bedre når det gjelder «dataferskhet», effektiviteten i kommunikasjon og sikkerhet. Ingen avspørring påkrevd
  • Webhooks tillater enkel ulike nivåer av omfang (konto/gruppe/bruker/ressurs). 
  • Webhooks er en mer moderne API-løsning, som muliggjør enklere konfigurasjon av moderne programmer
  • Flere webhooks kan konfigureres per område (konto/gruppe/bruker/ressurs), der tilbakeringinger måtte være unike
  • Webhooks gjør det mulig å velge dataene som skal returneres, der tilbakekall er en «alt eller ingenting»-løsning
  • Metadata som bæres med en webhook kan konfigureres (grunnleggende eller detaljert)
  • Webhooks er langt enklere å opprette, redigere eller deaktivere etter behov, siden brukergrensesnittet er fullstendig under administratorens kontroll.
Merk:

Dette dokumentet er primært fokusert på Webhooks-grensesnittet i Acrobat Sign-webprogrammet (tidligere Adobe Sign).

Utviklere som ser etter API-detaljer, kan finne mer informasjon her:

Forutsetninger

Du må tillate IP-områdene for webhooks gjennom nettverkssikkerheten din for at tjenesten skal fungere.

Den eldre tjenesten for tilbakekall av nettadresse i REST v5 bruker de samme IP-områdene som webhook-tjenesten.

Administratorer kan logge på Adobe Admin Console for å legge til brukere. Når du er logget på, går du til administratormenyen og ruller ned til Webhooks.

Slik brukes det

Administratorer må først ha en webhook-tjeneste, klar til å godta innkommende push fra Acrobat Sign. Det er mange alternativer i denne forbindelse, og så lenge tjenesten kan godta POST- og GET-forespørsler, vil webhooken være vellykket.

Når tjenesten er på plass, kan en Acrobat Sign-administrator opprette en ny webhook fra Webhook-grensesnittet i Konto-menyen på Acrobat Sign-området.

Administratorer kan konfigurere webhooken til å utløse for avtale-, webskjema- (Widget) eller send samlet- (MegaSign) hendelser. Ressursen for bibliotekmal (biblioteksdokument) kan også konfigureres via API-en.

Omfanget av webhooken kan inkludere hele kontoen eller individuelle grupper gjennom administratorgrensesnittet. API-en gir mer detaljer ved valg av BRUKER- eller RESSURS-omfang.

Datatypen som pushes til nettadressen, kan konfigureres og kan inkludere ting som avtaleinformasjon, deltakerinformasjon, dokumentinformasjon og så videre.

Når webhooken er konfigurert og lagret, vil Acrobat Sign pushe et nytt JSON-objekt til den definerte nettadressen hver gang den abonnerte hendelsen er utløst. Ingen pågående manipulering av webhooken er nødvendig med mindre du vil endre hendelsesutløserkriteriene eller JSON-nyttelasten.

Bekreftelse av hensikten med webhook-URL-adressen

Før en webhook registreres, bekrefter Acrobat Sign om webhook-nettadressen som er angitt i registreringsforespørselen har til hensikt å motta varsler eller ikke. For dette formålet, når Acrobat Sign mottar en ny webhook-registreringsforespørsel, sender den først en bekreftelsesforespørsel til webhook-nettadressen. Denne bekreftelsesforespørselen er en HTTPS GET-forespørsel sendt til webhook-URL-adressen. Denne forespørselen har en tilpasset HTTP-topptekst X-AdobeSign-ClientId. Verdien i denne toppteksten er satt til klient-ID (program-ID) for API-programmet som forespør å opprette/registrere webhooken. For å lykkes med å registrere en webhook svarer webhook-nettadressen på denne bekreftelsesforespørselen med en 2XX-svarkode OG den MÅ dessuten sende tilbake samme klient-ID-verdi på én av følgende to måter:

  • Enten i et svarhode X-AdobeSign-ClientId. Dette er den samme toppteksten som sendes i forespørselen, og blir gjentatt i svaret.
  • Eller i JSON-svarteksten med nøkkelen til xAdobeSignClientId og tilhørende verdi er den samme klient-ID-en som sendes i forespørselen.

Webhooken vil bare bli registrert på et vellykket svar (2XX svarkode) og validering av klient-ID enten i toppteksten eller svarteksten. Hensikten med denne bekreftelsesforespørselen er å vise at webhook-nettadressen din virkelig ønsker å motta varsler på den nettadressen. Hvis du ved et uhell skrev inn feil nettadresse, vil nettadressen ikke svare riktig på bekreftelsen av hensiktsforespørselen, og Acrobat Sign vil ikke sende noen varsler til den nettadressen. I tillegg kan webhook-nettadressen også bekrefte at den bare vil motta varsler gjennom webhookene som er registrert av et bestemt program. Dette kan gjøres ved å validere klient-ID-en for programmet som er sendt i X-AdobeSign-ClientId-hodet. Hvis webhook-nettadressen ikke gjenkjenner klient-ID-en, MÅ DEN IKKE svare med suksessresponskoden, og Acrobat Sign vil sørge for at nettadressen ikke er registrert som en webhook.

Verifisering av webhook-nettadressekall vil bli foretatt i følgende scenarier:

  • Registrerer Webhook: Hvis denne verifiseringen av webhook-nettadressekall mislykkes, blir ikke webhooken opprettet.
  • Oppdaterer Webhook: INAKTIV til AKTIV: Hvis denne bekreftelsen av webhook-nettadressekall mislykkes, endres ikke webhook-tilstanden til AKTIV.

Slik svarer du på et webhook-varsel

Acrobat Sign utfører en implisitt intensjonsbekreftelse i hver webhook-varslingsforespørsel som sendes til webhook-nettadressen. Dermed inneholder hver webhook-varsling HTTPS-forespørsel også det egendefinerte HTTP-hodet kalt X-AdobeSign-ClientId. Verdien av denne overskriften er klient-IDen (Applikasjon-ID) til applikasjonen der webhooken ble opprettet. Vi vil vurdere webhook-varselet levert hvis, og bare hvis et vellykket svar (2XX svarkode) returneres og klient-ID-en sendes enten i HTTP-toppteksten (X-AdobeSign-ClientId) eller i en JSON-responstekst med nøkkelen som xAdobeSignClientId og verdi som samme klient-ID, ellers vil vi prøve å levere varselet til webhook-nettadressen til forsøkene er utløpt.

Hvordan aktivere eller deaktivere

Tilgang til Webhook-funksjonen er aktivert som standard for kontoer på Enterprise-nivå.

Administratorer på gruppenivå kan opprette/kontrollere webhook som bare opererer i gruppen.

Tilgang til Webhook-siden finnes på venstre side av Administrator-menyen.

Gå til Webhook-fanen

Samtidighetsbasert prisbegrensning

Webhook-opprettings- og varslingshendelser (og tilbakekall) er begrenset i antallet samtidige varsler som aktivt leveres til kunden fra Acrobat Sign-systemet. Denne grensen gjelder for kontoen, slik at den inkluderer alle grupper innenfor kontoen.
Denne typen hastighetsbegrensning forhindrer at en dårlig utformet konto konsumerer en uforholdsmessig stor mengde serverressurser, og påvirker dermed alle andre kunder i det servermiljøet negativt.

Antallet samtidige hendelser per konto er beregnet for å sikre at kontoer med velfungerende webhook mottar varslene sine på kortest mulig tid, og sjelden vil møte en situasjon der varsler blir forsinket på grunn av for mange forespørsler. Gjeldende grenseverdier er:

Handling
(Hendelse)

Maksimum
samtidige
hendelser

Beskrivelse

Opprette webhook

10

På det meste er 10 samtidige forespørsler om webhook-opprettelse er tillatt per konto.
Forespørsler som overskrider denne grensen resulterer i en svarkode med 429 TOO_MANY_REQUESTS.

Webhook/tilbakeringingsvarsel

30

Maksimalt 30 samtidige webhook- og tilbakeringingsvarsler er tillatt per konto.
Varsler som overskrider denne grensen vil prøve på nytt i henhold til eksponentielt tilbakeslag til de leveres.

Anbefalte fremgangsmåter

  • Abonner på spesifikke, nødvendige hendelser for å begrense antall HTTPS-forespørsler til serveren – desto mer spesifikk du kan gjøre webhooks, desto mindre volum må du bla gjennom.
  • Vær motstandsdyktig mot duplikater – hvis du har mer enn én app som deler samme nettadresse og samme bruker som er tilordnet hver app, blir den samme hendelsen sendt til nettadressen flere ganger (én gang per app). I noen tilfeller kan webhooken din motta dupliserte hendelser. Webhook-applikasjonen din bør være tolerant for dette og trekke fra med hendelses-ID.
  • Svar alltid raskt på webhooks – appen din har bare ti sekunder på seg til å svare på webhook-forespørsler. Når det gjelder bekreftelsesforespørselen er dette sjelden et problem, siden appen din ikke trenger å gjøre noe ordentlig arbeid for å svare. For varslingsforespørsler vil imidlertid appen vanligvis gjøre noe som tar tid som svar på forespørselen. Det anbefales å arbeide på en separat tråd eller asynkront ved hjelp av en kø for å sikre at du kan svare innen fem sekunder
  • Administrer samtidighet – når en bruker gjør en rekke endringer i rask rekkefølge, vil appen sannsynligvis motta flere varsler for samme bruker omtrent samtidig. Hvis du ikke er forsiktig med hvordan du administrerer samtidighet, kan det ende med at appen din behandler de samme endringene for samme bruker mer enn én gang. For å kunne dra nytte av webhooks for Acrobat Sign, må en klar forståelse av bruken av informasjonen forstås. Sørg for å stille spørsmål som: 
    • Hvilke data vil du returnere i nyttelasten? 
    • Hvem får tilgang til denne informasjonen? 
    • Hvilke beslutninger eller rapportering vil bli generert?
  • Anbefalinger for mottak av signert dokument – det er flere faktorer å ta hensyn til når du bestemmer hvordan du skal motta en signert PDF fra Acrobat Sign på dokumentbehandlingssystemet. 

Selv om det er fullt akseptabelt å bare velge alternativet Signert avtaledokument mens du oppretter en webhook, kan du vurdere å bruke Acrobat Sign API for å hente dokumentene når en utløsende hendelse (for eksempel avtalestatusen Fullført) mottas.

Ting å huske på ...

JSON-størrelsesbegrensning

JSON-nyttelaststørrelsen er begrenset til 10 MB.

Hvis en hendelse genererer en større nyttelast, vil en webhook bli utløst. Men de betingede parameterattributtene, hvis de finnes i forespørselen, vil bli fjernet for å redusere størrelsen på nyttelasten. 

«ConditionalParametersTrimmed» returneres i svaret når dette skjer for å informere klienten om at informasjonen med  conditionalParameters  har blitt fjernet.

conditionalParametersTrimmed” er et matriseobjekt som inneholder informasjon om nøklene som er trimmet.

Avkortingen vil gjøres i følgende rekkefølge:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Signerte dokumenter vil bli avkortet først, etterfulgt av deltakerinfo, dokumentinfo og til slutt detaljert informasjon.

Dette kan for eksempel skje på en avtalefullføringshendelse hvis den inkluderer signert dokument (base 64-kodet), eller for en avtale med flere skjemafelt

Varsler om webhook

Acrobat Sign-webhook leverer varsler til avsenderen av avtalen, og enhver webhook som er konfigurert i gruppen som avtalen ble sendt fra. Kontoomfangede webhook mottar alle hendelser.

Prøv på nytt når lyttetjenesten er nede

Hvis måladressen for webhooken er nede av en eller annen grunn, setter Acrobat Sign JSON i kø og prøver pushet på nytt i en progressiv syklus over 72 timer.

De uleverte hendelsene blir værende i en prøv på nytt-kø, og det gjøres en best mulig innsats i løpet av de neste 72 timene for å levere varslene i den rekkefølgen de oppsto.

Strategien for å prøve å levere varsler på nytt er en dobling av tiden mellom forsøk, og starter med et ett minutts intervall som øker til hver 12. time, og resulterer i 15 nye forsøk i løpet av 72 timer.

Hvis webhook-mottakeren ikke svarer innen 72 timer, og det ikke har vært noen vellykkede varslingsleveranser de siste syv dagene, deaktiveres webhooken. Ingen varsler vil bli sendt til denne nettadressen før webhook er aktivert igjen.

Alle varsler mellom når webhook er deaktivert og deretter aktivert igjen, vil gå tapt.

Få hjelp raskere og enklere

Ny bruker?