Käyttöopas Peruuta

 Acrobat Signin webhookien yleiskatsaus 

 

Adobe Acrobat Sign -opas

Uudet ominaisuudet

Aloita käyttö

Hallinnoi

Sopimusten lähetys, allekirjoitus ja hallinta

Edistyneet sopimustoiminnot ja -työnkulut

Muihin tuotteisiin integrointi

Acrobat Sign Developer

Tuotetuki ja vianetsintä

Yleiskatsaus

Webhook on käyttäjän määrittämä HTTPS-pyyntö, joka laukaistaan, kun tilattu tapahtuma tapahtuu lähdesivustolla (tässä tapauksessa Adobe Acrobat Signissa).

Käytännössä Webhook on REST-palvelu, joka hyväksyy dataa tai datavirran.

Webhookit on tarkoitettu palvelujen väliseen viestintään PUSH-mallissa.

Kun tilattu tapahtuma toteutuu, Acrobat Sign luo HTTPS POST:in JSON-rungolla ja toimittaa sen määritettyyn URL-osoitteeseen.

Varmista ennen webhookien määrittämistä, että verkkosi hyväksyy toimintojen edellyttämät IP-osoitealueet.

 

Vanhaan vastakutsumenetelmään verrattuna webhookeissa on useita etuja kuten:

  • Järjestelmänvalvojat voivat ottaa käyttöön omia webhookeja, jolloin vastakutsun URL-osoitetta ei tarvitse pyytää Acrobat Sign -tuesta
  • Webhookit ovat parempia, jos datan ”tuoreus”, viestinnän tehokkuus, ja turvallisuus otetaan huomioon. Äänestystä ei vaadita
  • Webhookit mahdollistavat eri laajuustasoja (Tili/Ryhmä/Käyttäjä/Resurssi) helposti. 
  • Webhookit ovat nykyaikainen API-ratkaisu, joka helpottaa nykyaikaisten sovellusten konfigurointia
  • Tietylle vaikutusalueelle voidaan määrittää useita webhookeja (Tili/Ryhmä/Käyttäjä/Resurssi), kun taas takaisinsoittojen oli oltava yksilöllisiä
  • Webhookeilla voidaan valita palautettava data, kun taas vastakutsut ovat ”kaikki tai ei mitään” -ratkaisu
  • Webhookilla kuljetettavat metatiedot voidaan konfiguroida (Perus- tai Yksityiskohtaisesti)
  • Webhookit on paljon helpompi luoda, muokata, tai poistaa käytöstä tarpeen mukaan, koska käyttöliittymä on täysin ylläpitäjän hallinnassa.
Huomautus:

Tämä asiakirja keskittyy ensisijaisesti Webhooks-käyttöliittymään Acrobat Sign -verkkosovelluksessa (Aiemmin Adobe Sign).

API-tietoja etsivät kehittäjät löytävät lisätietoja täältä:

Edellytykset

Sinun täytyy sallia webhookien IP-alueet verkkosuojauksen kautta, jotta palvelu toimii. 

REST v5:n vanha takaisinsoitto-URL-palvelu käyttää samoja IP-osoitealueita kuin webhook-palvelu.

Järjestelmänvalvojat voivat kirjautua Adobe Admin Consoleen käyttäjien lisäämistä varten. Siirry sisäänkirjautumisen jälkeen järjestelmänvalvojan valikkoon ja vieritä alas kohtaan Webhookit.

Miten sitä käytetään

Ylläpitäjillä on ensiksi oltava webhook-palvelu, joka on valmis hyväksymään Acrobat Signista saapuvan push-operaation. Tältä osin on monia vaihtoehtoja, ja niin kauan kuin palvelu voi hyväksyä POST- ja GET- pyyntöjä, webhook on onnistunut.

Kun palvelu on käytössä, Acrobat Signin ylläpitäjä voi luoda uuden webhookin Webhook-käyttöliittymästä Acrobat Sign -sivuston Tili-valikossa.

Ylläpitäjät voivat määrittää webhookin laukaisemaan sopimus-, Web-lomake (pienoisohjelma) tai erälähetys (MegaSign) -tapahtumia. Myös kirjastomalliresurssi (kirjastodokumentti) voidaan määrittää API:n kautta.

Webhookin vaikutusalueeseen voi kuulua koko tili tai yksittäiset ryhmät järjestelmänvalvojan käyttöliittymän kautta. API sallii paremman hajautuksen KÄYTTÄJÄ- tai RESURSSI-käyttöalueiden valinnalla.

URL-osoitteeseen työnnettyjen tietojen tyyppiä voidaan muokata, ja se voi sisältää muiden muassa sopimus-, osallistuja- ja asiakirjatietoja.

Kun webhook on määritetty ja tallennettu, Acrobat Sign työntää uuden JSON-objektin määritettyyn URL-osoitteeseen joka kerta, kun käynnistystapahtuma laukaistaan. Webhookia ei tarvitse jatkuvasti käsitellä, ellet halua muuttaa tapahtumanlaukaisuperusteita tai JSON-hyötykuormaa.

Webhookin URL-osoitteen tarkoituksen vahvistaminen

Ennen webhookin rekisteröintiä Acrobat Sign varmistaa, ottaako rekisteröintipyynnössä ilmoitettu webhookin URL-osoite ilmoituksia vastaan vai ei. Sen vuoksi Acrobat Sign lähettää ensimmäiseksi vahvistuspyynnön webhookin URL-osoitteeseen, kun se vastaanottaa uuden webhookin rekisteröintipyynnön. Tämä vahvistuspyyntö on HTTPS GET -pyyntö, joka lähetetään webhookin URL-osoitteeseen. Tässä pyynnössä on mukautettu HTTP-otsikko X-AdobeSign-ClientId. Tämän otsikon arvoksi määritetään webhookin luomista/rekisteröintiä pyytävän API-sovelluksen asiakastunnus (sovellustunnus). Jotta webhookin rekisteröinti varmasti onnistuu, webhookin URL-osoitteen TÄYTYY vastata tähän vahvistuspyyntöön 2XX-vastauskoodilla. LISÄKSI sen TÄYTYY palauttaa sama asiakastunnuksen arvo yhdellä seuraavista kahdesta tavasta:

  • Joko vastausotsikossa X-AdobeSign-ClientId. Tämä on sama otsikko, joka lähetettiin pyynnössä ja toistettiin vastauksessa.
  • Tai JSON-vastausosassa avaimella xAdobeSignClientId, jonka arvo on sama kuin pyynnössä lähetetty asiakastunnus.

Webhook rekisteröidään onnistuneesti vain onnistuneen vastauksen (vastauskoodi 2XX) ja asiakastunnuksen validoinnin myötä joko ylätunnisteessa tai vastausosassa. Vahvistuspyynnön tarkoituksena on näyttää toteen, että webhookin URL-osoite haluaa saada ilmoituksia kyseiseen URL-osoitteeseen. Jos syötit vahingossa väärän URL-osoitteen, URL-osoite ei vastaa oikein aiepyynnön vahvistukseen, eikä Acrobat Sign lähetä ilmoituksia kyseiseen URL-osoitteeseen. Lisäksi webhookin URL-osoite voi vahvistaa saavansa ilmoituksia vain jonkin tietyn sovelluksen rekisteröimien webhookien kautta. Tämä onnistuu vahvistamalla X-AdobeSign-ClientId-otsakkeessa välitetyn sovelluksen asiakastunnus. Jos webhookin URL-osoite ei tunnista kyseistä asiakastunnusta, se EI SAA vastata onnistuneen vastauksen koodilla, minkä jälkeen Acrobat Sign huolehtii, että URL-osoitetta ei rekisteröidä webhookiksi.

Webhookin URL-kutsu vahvistetaan seuraavissa tilanteissa:

  • Webhookin rekisteröinti: Jos tämä webhook-URL-kutsun vahvistus epäonnistuu, webhookia ei luoda.
  • Webhookin päivittäminen: EI-AKTIIVISESTA AKTIIVISEKSI: Jos webhook-URL-kutsun vahvistaminen epäonnistuu, webhookin tilaa ei vaihdeta AKTIIVISEKSI.

Webhook-ilmoitukseen vastaaminen

Acrobat Sign suorittaa implisiittisen aievahvistuksen jokaisessa webhookin ilmoituspyynnössä, joka webhookin URL-osoitteeseen lähetetään. Siten jokainen webhook-ilmoituksen HTTPS-pyyntö sisältää myös mukautetun HTTP-otsakkeen nimeltä X-AdobeSign-ClientId. Tämän otsikon arvo on Webhook-sovelluksen luoneen sovelluksen asiakastunnus (Application ID). Pidämme webhook-ilmoitusta onnistuneesti vastaanotettuna, jos – ja vain jos – onnistunut vastaus (2XX vastauskoodi) palautetaan ja asiakkaan tunnus lähetetään joko HTTP-otsikossa (X-AdobeSign-ClientId) tai JSON-vastauksen rungossa, jonka avain on xAdobeSignClientId ja arvo sama asiakastunnus. Muussa tapauksessa yritämme toimittaa ilmoituksen webhookin URL-osoitteeseen, kunnes uusintayritykset on käytetty.

Käyttöönotto tai poistaminen käytöstä

Webhooks-ominaisuuteen pääsy on oletuksena käytössä Enterprise-tason tileillä.

Ryhmätason ylläpitäjät voivat luoda/hallita webhookeja, jotka toimivat vain heidän ryhmässään.

Pääsy Webhooks-sivulle löytyy Admin-valikon vasemmasta listasta.

Siirry Webhooks-välilehteen

Samanaikaisuuteen perustuva määrän rajoittaminen

Webhookien (ja vastakutsujen) luonti- ja ilmoitustapahtumien määrä on rajoitettu niiden samanaikaisten ilmoitusten osalta, jotka lähetetään aktiivisesti asiakkaalle Acrobat Sign -järjestelmästä. Tämä rajoitus koskee tiliä, jotta se sisältäisi kaikki tilin ryhmät.
Tämäntyyppinen määrän rajoittaminen estää yhtä huonosti suunniteltua tiliä kuluttamasta suhteettoman paljon palvelinresursseja, mikä vaikuttaa negatiivisesti kaikkiin muihin asiakkaisiin kyseisessä palvelinympäristössä.

Samanaikaisten tapahtumien määrä tiliä kohden on laskettu sen varmistamiseksi, että tilit, joissa on hyvin toimivia webhookeja, saavat ilmoituksensa mahdollisimman lyhyessä ajassa ja kohtaavat harvoin tilanteen, jossa ilmoitukset viivästyvät liian monien pyyntöjen vuoksi. Nykyiset kynnysarvot ovat:

Toiminta
(Tapahtuma)

Maksimimäärä
samanaikaisia
tapahtumia

Kuvaus

Webhookin luominen

10

Tiliä kohden sallitaan enintään 10 samanaikaista webhookin luontipyyntöä.
Tämän rajan ylittävät pyynnöt johtavat 429 TOO_MANY_REQUESTS -vastauskoodiin.

Webhook-/vastakutsuilmoitus

30

Tiliä kohden sallitaan enintään 30 samanaikaista webhook- ja vastakutsuilmoitusta.
Tämän rajan ylittäviä ilmoituksia yritetään uudelleen eksponentiaalisen viiveen mukaisesti, kunnes ne toimitetaan.

Parhaat käytännöt

  • Tilaa vain ne tapahtumat, joita tarvitset, jotta palvelimen HTTPS-pyyntöjen määrä vähenee – Mitä tarkempia webhookeja teet, sitä vähemmän tietoja sinun tarvitsee käydä läpi.
  • Vastusta kaksoiskappaleita - Jos useampi kuin yksi sovellus jakaa saman webhookin URL-osoitteen ja sama käyttäjä on kartoitettu kuhunkin sovellukseen, sama tapahtuma lähetetään webhookiisi useita kertoja (kerran sovellusta kohden). Joissakin tapauksissa webhook voi vastaanottaa päällekkäisiä tapahtumia. Webhook-sovelluksesi pitäisi olla suvaitsevainen tätä kohtaan ja deduplikoida tapahtumatunnuksen mukaan.
  • Vastaa webhookeihin aina nopeasti – Sovelluksellasi on vain viisi sekuntia aikaa vastata webhook-pyyntöihin. Vahvistuspyynnön osalta tämä on harvoin ongelma, koska sovelluksesi ei tarvitse tehdä raskasta työtä vastatakseen. Sen sijaan ilmoituspyyntöjen kohdalla pyyntöön vastaaminen vie sovellukselta yleensä aikaa. On suositeltavaa käsitellä erillistä säiettä tai käyttää asynkronisesti jonoa, millä varmistetaan vastaus viiden sekunnin kuluessa
  • Hallinnoi rinnakkaisuutta - Kun käyttäjä tekee muutoksia nopeasti peräkkäin, sovellus todennäköisesti ottaa vastaan useita ilmoituksia samalle käyttäjälle suunnilleen samaan aikaan. Jos et ole varovainen samanaikaisuuden hallinnoinnissa, sovelluksesi saattaa käsitellä samoja muutoksia samalle käyttäjälle useammin kuin kerran. Jotta Acrobat Signin webhookeja voidaan hyödyntää, tietojen käyttö on ymmärrettävä selkeästi. Muista esittää kysymyksiä, kuten: 
    • Mitä tietoja haluat palauttaa hyötykuormassa? 
    • Kuka käyttää näitä tietoja? 
    • Mitä päätöksiä tai raportointia syntyy?
  • Suositukset allekirjoitetun asiakirjan vastaanottamisesta – On otettava huomioon useita tekijöitä, kun ratkaistaan, miten Acrobat Signissa allekirjoitettu PDF-tiedosto vastaanotetaan asiakirjahallintajärjestelmässä. 

Vaikka on täysin hyväksyttävää valita vain Allekirjoitettu sopimus -asiakirja vaihtoehto webhookin luomisen yhteydessä, voit harkita Acrobat Sign API: n käyttöä asiakirjojen hakemisen laukaisevan tapahtuman (kuten sopimuksen tila Complete) vastaanottamisen yhteydessä.

Muista seuraavat asiat...

JSON-kokorajoitus

JSON-hyötykuorma on rajoitettu 10 MB:iin.

Jos tapahtuma tuottaa suuremman hyötykuorman, webhook laukaistaan, mutta ehdollisten parametrien attribuutit poistetaan hyötykuorman pienentämiseksi, jos niitä on pyynnössä. 

Kun näin tapahtuu, vastauksessa palautetaan ”ConditionalParametersTrimmed” ilmoituksena asiakkaalle siitä, että conditionalParameters-tiedot on poistettu.

conditionalParametersTrimmed” on ryhmäobjekti, joka sisältää rajattuja avaimia koskevat tiedot.

Katkaisu tehdään seuraavassa järjestyksessä :

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Allekirjoitetut asiakirjat katkaistaan ensin, sen jälkeen osallistujatiedot, asiakirjatiedot ja lopuksi yksityiskohtaiset tiedot.

Tämä voi tapahtua esimerkiksi sopimuksen valmistumistapahtumassa, jos se sisältää myös allekirjoitetun asiakirjan (pohja 64 koodattu), tai sopimuksessa, jossa on useita lomakekenttiä

Webhook-ilmoitukset

Acrobat Sign -webhookit toimittavat ilmoituksia sopimuksen lähettäjälle ja kaikille webhookeille, jotka on määritetty ryhmässä, josta sopimus lähetettiin. Tilin piiriin kuuluvat webhookit vastaanottavat kaikki tapahtumat.

Yritä uudelleen, kun kuuntelupalvelu on alhaalla

Jos kohde-URL-osoite ei jostakin syystä toimi, Acrobat Sign asettaa JSONin jonoon ja yrittää suorittaa siirron progressiivisesti 72 tunnin ajan.

Toimittamattomat tapahtumat muutetaan pysyviksi uudelleenyritysjonossa, ja ilmoitukset yritetään toimittaa niiden ilmenemisjärjestyksessä seuraavan 72 tunnin ajan.

Ilmoitusten uudelleentoimituksen strategiana on kaksinkertaistaa yritysten välinen aika, alkaen 1 minuutin aikavälillä, joka kasvaa 12 tunnin välein. Tuloksena on 15 yritystä 72 tunnin aikana.

Jos webhook-vastaanotin ei vastaa 72 tunnin kuluessa, eikä ilmoituksia ole toimitettu onnistuneesti viimeisen seitsemän päivän aikana, webhook poistetaan käytöstä. Tähän URL-osoitteeseen ei lähetetä ilmoituksia ennen kuin webhook aktivoidaan uudelleen.

Kaikki ilmoitukset, jotka tehdään webhookin käytöstäpoiston ja sen jälkeisen uudelleenkäyttöönoton välillä menetetään.

Pyydä apua nopeammin ja helpommin

Oletko uusi käyttäjä?