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ä:

REST v6 -tiedot

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.

Kirjaudu Admin Consoleen

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.

Kuten edellä mainittiin, otsikko 'X-AdobeSign-ClientId', joka sisältyy jokaiseen Signin ilmoituspyyntöön, tämän otsikon arvo (asiakastunnus) olisi palautettava vastauksena jommallakummalla seuraavista tavoista:

1. HTTP-otsikko X-AdobeSign-ClientId ja arvo asiakastunnuksena

Näyte Javascript-koodista, jolla haetaan asiakkaan tunnus, validoidaan se ja palautetaan se vastausotsikkoon
// Hae asiakastunnus var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Varmenna se if (clientid ==="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook luodaan { //Palauta se vastausotsikossa response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // oletusarvo }

Näyte PHP-koodiin asiakastunnuksen noutamiseksi, sen validoimiseksi ja sen palauttamiseksi vastausotsikkoon
<?php // Hae asiakastunnus $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Varmenna se if($clientid == "BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu { //Palauta se vastausotsikossa header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // oletusarvo } ?>

2. JSON-vastekehikko avaimella xAdobeSignClientId ja arvona sama asiakastunnus

Ota näyte Javascript-koodista, jotta voit noutaa asiakastunnuksen, vahvistaa sen ja palauttaa sen vastausrunkoon
// Hae asiakastunnus var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Varmenna se if (clientid ==="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook luodaan { var responseBody = { "xAdobeSignClientId" : clientid // Palauta asiakastunnus runkoon }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; }

Ota näyte Javascript-koodista, jotta voit noutaa asiakastunnuksen, vahvistaa sen ja palauttaa sen vastausrunkoon

// Hae asiakastunnus

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

//Varmenna se

if (clientid ==="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook luodaan

{

var responseBody = {

"xAdobeSignClientId" : clientid // Palauta asiakastunnus runkoon

};

response.headers['Content-Type'] = 'application/json';

response.body = responseBody;

response.status = 200;

}

Näyte PHP-koodista asiakkaan tunnuksen noutamiseksi, sen validoimiseksi ja palauttamiseksi vastaustekstissä
<?php // Hae asiakastunnus $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Varmenna se if($clientid == "BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu { //Palauta se vastaustekstissä header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // oletusarvo } ?>

Näyte PHP-koodista asiakkaan tunnuksen noutamiseksi, sen validoimiseksi ja palauttamiseksi vastaustekstissä

<?php

// Hae asiakastunnus

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Varmenna se

if($clientid == "BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu

{

//Palauta se vastaustekstissä

header("Content-Type: application/json");

$body = array('xAdobeSignClientId' => $clientid);

echo json_encode($body);

header("HTTP/1.1 200 OK"); // oletusarvo

}

Vastaustekstin JSON-näyte
{ "xAdobeSignClientId": "BGBQIIE7H253K6" }

Edellytykset

Tarvitset:

Microsoft-tilin, jolla on lupa luoda Azure-toimintosovelluksia
Olemassa olevan Azure-toimintosovelluksen, jonka voit luoda näin https://docs.microsoft.com/fi-fi/azure/azure-functions/functions-create-first-azure-function
Javascriptin perustiedot, jotta voit ymmärtää ja kirjoittaa koodin valitsemallasi kielellä

Vaiheet Acrobat Sign -webhookina toimivan Azure-funktioiden laukaisimen luomiseen

Voit luoda Javascript HTTP -liipaisintoiminnon näin:

1. Kirjaudu sisään Microsoft-tilisi kautta https://portal.azure.com/

2. Avaa Azure-toimintosovellus, joka näkyy Toimintosovellukset -välilehdellä.

Tämä avaa Azure-toimintosovellusten luettelon:

3. Valitse sovellus, johon haluat luoda tämän uuden toiminnon

4. Luo uusi Azure-toiminto napsauttamalla Luo (+) -painiketta

5. Valitse Webhook+ API skenaarioksi ja Javascript kieleksi

6. Napsauta Luo tämä toiminto

Luodaan uusi toiminto, joka pystyy käsittelemään saapuvan API-pyynnön.

Lisää logiikka rekisteröidäksesi Acrobat Sign webhook

Ennen webhookin rekisteröintiä Acrobat Sign varmistaa, aikooko rekisteröintipyynnössä ilmoitettu webhookin URL-osoite todella vastaanottaa ilmoituksia vai ei. Tätä varten, kun Acrobat Sign vastaanottaa uuden webhookin rekisteröintipyynnön, se tekee ensin vahvistuspyynnön webhookin URL-osoitteeseen. Tämä vahvistuspyyntö on HTTPS GET -hakupyyntö, joka lähetetään webhookin URL-osoitteeseen mukautetulla HTTP-otsakkeella X-AdobeSign-ClientId. Tämän otsakkeen arvoksi asetetaan sen sovelluksen asiakastunnus, joka pyytää verkkokoukun luomista/rekisteröintiä. Webhookin rekisteröinnin onnistumisen varmistamiseksi webhookin URL-osoitteen on vastattava tähän vahvistuspyyntöön 2XX-vastauskoodilla. Tämän LISÄKSI sen täytyy lähettää sama asiakastunnuksen arvo takaisin jommallakummalla seuraavista tavoista.

Voit seurata kahta vaihtoehtoa:

Vaihtoehto 1: Välitä asiakastunnus X-AdobeSign-ClientId:ssä vastauksen otsakkeena

Välitä X-AdobeSign-ClientId vastauksen otsakkeessa. Se on sama otsake, joka välitettiin pyynnössä, ja se on toistettava vastauksessa.

Korvaa Index.js-tiedosto seuraavalla:

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Vahvista, että saapuvan asiakkaan tunnus on aito

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Oletusarvo on 200 */ / mikä tahansa 2XX vastaus on hyväksyttävä

body: "Ilmoitus hyväksytty",

headers : {

'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

}

};

}

else {

context.res = {

status: 400,

body: "Hups!! Laiton kutsu tunnistettu"

};

}

context.done();

};

Testaa käyttäytymistä jäljittelemällä pyyntöä:

1. Napsauta Testi-painiketta äärioikeasta kulmasta

2. Jäljittele valepyyntöä

Vaikka vastausten otsikot eivät näy yllä, mutta voit tarkkailla sitä pilkkaamalla sitä postinkantajalla/DHC:llä tai muulla palvelulla.

Vaihtoehto 2: Välitä asiakastunnus vastaustekstissä avaimella xAdobeSignClientId

JSON-vastauksen tekstiosassa avaimella xAdobeSignClientId, jonka arvo on sama kuin pyynnön otsakkeessa lähetetty asiakastunnus.

Korvaa Index.js-tiedosto seuraavalla:

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Vahvista, että saapuvan asiakkaan tunnus on aito

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Oletusarvo on 200 */ / mikä tahansa 2XX vastaus on hyväksyttävä

body: {

'xAdobeSignClientId' : clientId

headers : {

'Content-Type' : 'application/json'

}

};

}

else {

context.res = {

status: 400,

body: "Hups!! Laiton kutsu tunnistettu"

};

}

context.done();

};

Testaa käyttäytymistä jäljittelemällä pyyntöä

1. Napsauta Testi-painiketta äärioikeasta kulmasta

2. Jäljittele valepyyntöä

Huomaa myös, että clientID:ltä odotetaan samaa käyttäytymistä, kun Webhookin URL-osoite vastaanottaa POST-ilmoituksia.

Käyttövalmis

Kun olet vahvistanut käyttäytymisen, webhookin URL-osoite toimii Acrobat Sign -standardien mukaisesti. Voit päivittää mukautettua logiikkaa edelleen tarpeidesi mukaisesti.

Hae toiminnon URL

Napsauta Hae toiminnon URL

Kopioi URL-osoite ja käytä sitä webhooken luomiseen Acrobat Signissa.

AWS Lambda -toiminnon luominen

Voit luoda AWS Lambda -toiminnon näin: kirjaudu AWS-hallintakonsoliin ja valitse palveluluettelosta AWS Lambda -palvelu.

Napsauta Create a Lambda function using ”Author From Scratch” -vaihtoehtoa
Anna Configure function -sivulla toiminnon nimi ”lambdaWebhooks” ja valitse Runtimeksi Node.js 4.3
Valitse rooliksi olemassa oleva rooli tai luo uusi rooli mallipohjista
- Jos olet valinnut Luo uusi rooli malleista, syötä roolin nimi (esim. rooli-lamda) ja valitse Käytännön malli -luettelosta Yksinkertaiset mikropalveluiden käyttöoikeudett
Napsauta Luo toiminto-painiketta

Valitse uudella AWS Lambda -toimintosivulla ”Muokkaa koodia rivitilassa” ”Koodin syöttötyyppi”, pidä index.handler käsittelijänä.
Lisää logiikka rekisteröidäksesi Acrobat Signin webhook
Ennen webhookin rekisteröintiä Acrobat Sign varmistaa, aikooko rekisteröintipyynnössä ilmoitettu webhookin URL-osoite todella vastaanottaa ilmoituksia vai ei. Tätä varten, kun Acrobat Sign vastaanottaa uuden webhookin rekisteröintipyynnön, se tekee ensin vahvistuspyynnön webhookin URL-osoitteeseen. Tämä vahvistuspyyntö on HTTPS GET -hakupyyntö, joka lähetetään webhookin URL-osoitteeseen mukautetulla HTTP-otsakkeella X-AdobeSign-ClientId. Tämän otsakkeen arvoksi asetetaan sen sovelluksen asiakastunnus, joka pyytää verkkokoukun luomista/rekisteröintiä. Webhookin rekisteröinnin onnistumisen varmistamiseksi webhookin URL-osoitteen on vastattava tähän vahvistuspyyntöön 2XX-vastauskoodilla. Tämän LISÄKSI sen täytyy lähettää sama asiakastunnuksen arvo takaisin jommallakummalla seuraavista tavoista. Huomaa myös, että clientID:ltä odotetaan samaa käyttäytymistä, kun Webhookin URL-osoite vastaanottaa POST-ilmoituksia.

Seuraa jompaakumpaa tapausta:

Tapaus 1: Välitä asiakastunnus X-AdobeSign-ClientId:ssä vastauksen otsakkeena
- Välitä X-AdobeSign-ClientId vastauksen otsikkeessa. Se on sama otsake, joka välitettiin pyynnössä, ja se on toistettava vastauksessa.
  
  Koodinpätkä
  Korvaa indeksi.js-tiedostossa automaattisesti luotu koodinpätkä seuraavalla koodilla:

Näytesolmun JS-koodi hakee asiakastunnuksen, vahvistaa sen ja palauttaa sen sitten vastauksen otsakkeessa
exports.handler = function index(event, context, callback) { // Hae asiakastunnus var clientid = event.headers['X-AdobeSign-ClientId']; //Varmenna se if (clientid =="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Hups!! laiton kutsu"); } }

Näytesolmun JS-koodi hakee asiakastunnuksen, vahvistaa sen ja palauttaa sen sitten vastauksen otsakkeessa

exports.handler = function index(event, context, callback) {

// Hae asiakastunnus

var clientid = event.headers['X-AdobeSign-ClientId'];

//Varmenna se

if (clientid =="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu

{

var response = {

statusCode: 200,

headers: {

"X-AdobeSign-ClientId": clientid

}

};

callback(null,response);

}

else {

callback("Hups!! laiton kutsu");

}

Tapaus 2: Välitä Client ID vastaustekstissä avaimella xAdobeSignClientId

JSON-vastauksen tekstiosassa avaimella xAdobeSignClientId, jonka arvo on sama kuin pyynnön otsakkeessa lähetetty asiakastunnus.

Koodinpätkä

Korvaa Index.js-tiedosto seuraavalla:

Näytesolmun JS-koodi hakee asiakastunnuksen, vahvistaa sen ja palauttaa sen sitten vastauksen otsakkeessa
exports.handler = function index(event, context, callback) { // Hae asiakastunnus var clientid = event.headers['X-AdobeSign-ClientId']; //Varmenna se if (clientid =="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu { var responseBody = { xAdobeSignClientId : clientid }; var response = { statusCode: 200, body: JSON.stringify(responseBody) }; callback(null,response); } else { callback("Hups!! laiton kutsu"); } }

Näytesolmun JS-koodi hakee asiakastunnuksen, vahvistaa sen ja palauttaa sen sitten vastauksen otsakkeessa

exports.handler = function index(event, context, callback) {

// Hae asiakastunnus

var clientid = event.headers['X-AdobeSign-ClientId'];

//Varmenna se

if (clientid =="BGBQIIE7H253K6") //Korvaa 'BGBQIIE7H253K6' sen sovelluksen asiakastunnuksella, jonka avulla webhook on luotu

{

var responseBody = {

xAdobeSignClientId : clientid

};

var response = {

statusCode: 200,

body: JSON.stringify(responseBody)

};

callback(null,response);

}

else {

callback("Hups!! laiton kutsu");

}

Tallenna toiminto. Lambda-toiminto on luotu ja olemme melkein valmiita käyttämään sitä reaaliaikaisessa webhookissa.

AWS API -yhdyskäytävän määrittäminen

Jotta tämä Lambda olisi julkisesti saatavilla HTTP-menetelmällä, meidän on määritettävä AWS API -yhdyskäytävä käyttäen (yllä luotua) toimintoamme sovellusliittymän taustaosana.

Valitse AWS-hallintakonsolissa API Gateway AWS-palveluista ja napsauta Luo API-painiketta

Valitse Luo uusi API-sovellusliittymä -sivulta Uusi API-sovellusliittymä ja anna API-sovellusliittymän nimeksi webhooks.
Napsauta Luo API -painiketta
Valitse avautuvasta Toiminnot-luettelosta Luo resurssi -vaihtoehto
Valitse Konfiguroi väliresurssiksi -vaihtoehto ja kirjoita validoi Resurssin nimeksi ja {proxy+} kohtaan Resurssipolku
Jätä Enable API Gateway CORS -vaihtoehto valitsematta ja napsauta Luo resurssi -painiketta
Pidä Lambda-toiminnon välityspalvelin valittuna Integrointityypiksi ja valitse alue, johon olet luonut Lambda-toiminnon Lambda-alueen avautuvasta luettelosta (luultavasti sama alue, johon luot sovellusliittymän API-yhdyskäytävää).
Kirjoita validoi Lambda-toiminnoksi ja napsauta Tallenna-painiketta
Valitse Lisää Lambda-toimintoon käyttölupa -ponnahdusikkunasta OK.

Jos kaikki yllä mainitut vaiheet suoritetaan onnistuneesti, näet jotain tällaista:

API-sovellusliittymän käyttöönotto

Seuraava vaihe on tämän API-sovellusliittymän käyttöönotto, jotta se on valmiina käyttöön.

Valitse avautuvasta Toiminnot-valikosta Ota API käyttöön
Valitse [Uusi vaihe] Käyttöönottovaiheesta ja kirjoita prod (tai mitä tahansa, jolla tunnistat tämän vaiheen) vaiheen nimeen
Napsauta Ota käyttöön -painiketta

API-sovellusliittymä on nyt valmiina käyttöön, ja voit löytää kutsuttavan URL-osoitteen alla olevasta sinisestä ruudusta:

Ota tämä URL-osoite talteen, koska sinun on annettava se reaaliaikaisen webhookin URL-osoitteena.

Käyttövalmis

Homma on hoidettu. Käytä tätä yllä olevaa URL-osoitetta ”/{nodeJSfunctionName}” POST /webhooks-API-pyynnön loppuun lisättynä webhook URL-osoitteena. Kun oikea käyttäytyminen on vahvistettu, webhookin URL-osoite toimii
Acrobat Sign -standardien mukaisesti. Voit päivittää/lisätä mukautettua logiikkaa vaatimuksesi mukaisesti.

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.

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.

Lähettäjä: Käyttäjä A | Allekirjoittaja: Käyttäjä B | Jaetun sisällön saanut: Käyttäjä C

Käyttäjä A ja käyttäjä B ovat eri tileillä

Käyttäjä A ja käyttäjä C ovat eri tileillä

Käyttötapaus	Ilmoitus?	Kommentit/huomautukset
Käyttäjän A tilillä on TILI-tason webhook (käyttäjän A tai tilin järjestelmänvalvojan luoma).	Kyllä	TILI-tason webhook saa ilmoituksen kaikista kyseisellä tilillä käynnistetyistä tapahtumista.
Käyttäjän A tilillä on RYHMÄ-tason webhook (käyttäjän A tai tilin/ryhmän järjestelmänvalvojan luoma). Oletus: Käyttäjä A ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Kyllä	RYHMÄ-tason webhook saa ilmoituksen kaikista kyseisessä ryhmässä käynnistetyistä tapahtumista.
Käyttäjällä A on KÄYTTÄJÄ-tason webhook.	Kyllä	Lähettäjänä toimivan käyttäjän A KÄYTTÄJÄ-tason webhook käynnistetään.
Käyttäjällä A on RESURSSI-tason webhook (edellä lähetettyä sopimusta varten).	Kyllä

Käyttäjän B tilillä on TILI-tason webhook (käyttäjän B tai tilin järjestelmänvalvojan luoma).	Ei	Käyttäjän B TILI-tason webhook katsotaan allekirjoittajan webhookiksi.
Käyttäjän B tilillä on RYHMÄ-tason webhook (käyttäjän B tai tilin järjestelmänvalvojan luoma). Oletus: Käyttäjä B ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Ei	Käyttäjän B RYHMÄ-tason webhook katsotaan allekirjoittajan webhookiksi.
Käyttäjällä B on KÄYTTÄJÄ-tason webhook.	Ei	Käyttäjän B KÄYTTÄJÄ-tason webhook katsotaan allekirjoittajan webhookiksi.

Käyttäjän C tilillä on TILI-tason webhook (käyttäjän C tai tilin järjestelmänvalvojan luoma).	Ei	Käyttäjän C TILI-tason webhook katsotaan muun kuin tekijän webhookiksi.
Käyttäjän C tilillä on RYHMÄ-tason webhook (käyttäjän C tai tilin/ryhmän järjestelmänvalvojan luoma). Oletus: Käyttäjä C ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Ei	Käyttäjän C RYHMÄ-tason webhook katsotaan muun kuin tekijän webhookiksi.
Käyttäjällä C on KÄYTTÄJÄ-tason webhook.	Ei	Käyttäjän C KÄYTTÄJÄ-tason webhook katsotaan muun kuin tekijän webhookiksi.

Lähettäjä: Käyttäjä A | Allekirjoittaja: Käyttäjä B | Jaetun sisällön saanut: Käyttäjä C

Käyttäjä A, käyttäjä B ja käyttäjä C ovat samalla tilillä.

Käyttötapaus	Ilmoitus?	Huomautukset
Käyttäjän A tilillä on TILI-tason webhook (käyttäjän A tai tilin järjestelmänvalvojan luoma).	Kyllä	TILI-tason webhookit ilmoittavat tilin käynnistämistä tapahtumista.
Käyttäjän A tilillä on RYHMÄ-tason webhook (käyttäjän A tai tilin/ryhmän järjestelmänvalvojan luoma). Oletus: Käyttäjä A ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Kyllä	RYHMÄ tason webhookit ilmoittavat ryhmän käyttäjien käyttämistä tapahtumista.
Käyttäjällä A on KÄYTTÄJÄ-tason webhook.	Kyllä	Lähettäjänä toimivan käyttäjän A Käyttäjä-tason webhook käynnistetään.
Käyttäjällä A on RESURSSI-tason webhook (edellä lähetettyä sopimusta varten).	Kyllä

Käyttäjän B tilillä on TILI-tason webhook (käyttäjän B tai tilin järjestelmänvalvojan luoma).	Kyllä	Koska käyttäjä A ja käyttäjä B ovat samalla tilillä, TILI-tason webhook saa ilmoituksen kaikista kyseisellä tilillä käynnistetyistä tapahtumista.
Käyttäjän B tilillä on RYHMÄ-tason webhook (käyttäjän B tai tilin järjestelmänvalvojan luoma). Oletus: Käyttäjä A, käyttäjä B ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Kyllä	Koska käyttäjä A ja käyttäjä B ovat samassa ryhmässä, RYHMÄ-tason webhook saa ilmoituksen kaikista kyseisessä ryhmässä käynnistetyistä tapahtumista.
Käyttäjän B tilillä on RYHMÄ-tason webhook (käyttäjän B tai tilin järjestelmänvalvojan luoma). Oletus: Käyttäjä A ja käyttäjä B ovat eri ryhmissä.	Ei	Käyttäjän B RYHMÄ-tason webhook katsotaan allekirjoittajan webhookiksi. Käyttäjän A webhook (RESURSSI/KÄYTTÄJÄ/RYHMÄ/TILI) käynnistetään.
Käyttäjällä B on KÄYTTÄJÄ-tason webhook.	Ei	Vastaanottajana käyttäjän B KÄYTTÄJÄ-tason webhookia ei käynnistetä.

Käyttäjän C tilillä on TILI-tason webhook (käyttäjän C tai tilin järjestelmänvalvojan luoma).	Kyllä	Koska käyttäjä A ja käyttäjä C ovat samalla tilillä, TILI-tason webhook saa ilmoituksen kaikista kyseisellä tilillä käynnistetyistä tapahtumista.
Käyttäjän C tilillä on RYHMÄ-tason webhook (käyttäjän C tai tilin/ryhmän järjestelmänvalvojan luoma). Oletus: Käyttäjä A, käyttäjä C ja ryhmän järjestelmänvalvoja ovat samassa ryhmässä.	Kyllä	Koska käyttäjä A ja käyttäjä C ovat samassa ryhmässä, RYHMÄ-tason webhook saa ilmoituksen kaikista kyseisessä ryhmässä käynnistetyistä tapahtumista.
Käyttäjän C tilillä on RYHMÄ-tason webhook (käyttäjän C tai tilin/ryhmän järjestelmänvalvojan luoma). Oletus: Käyttäjä A ja käyttäjä C ovat eri ryhmissä.	Ei	Käyttäjän C RYHMÄ-tason webhook katsotaan muun kuin tekijän webhookiksi. Käyttäjän A webhook (RESURSSI/KÄYTTÄJÄ/RYHMÄ/TILI) käynnistetään.
Käyttäjällä C on KÄYTTÄJÄ-tason webhook.	Ei	Käyttäjän C KÄYTTÄJÄ-tason webhook katsotaan muun kuin tekijän webhookiksi.

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ä?

Acrobat Signin webhookien yleiskatsaus

Yleiskatsaus

Edellytykset

Miten sitä käytetään

Webhookin URL-osoitteen tarkoituksen vahvistaminen

Webhook-ilmoitukseen vastaaminen

1. HTTP-otsikko X-AdobeSign-ClientId ja arvo asiakastunnuksena

2. JSON-vastekehikko avaimella xAdobeSignClientId ja arvona sama asiakastunnus

Edellytykset

Vaiheet Acrobat Sign -webhookina toimivan Azure-funktioiden laukaisimen luomiseen

Lisää logiikka rekisteröidäksesi Acrobat Sign webhook

Vaihtoehto 1: Välitä asiakastunnus X-AdobeSign-ClientId:ssä vastauksen otsakkeena

Vaihtoehto 2: Välitä asiakastunnus vastaustekstissä avaimella xAdobeSignClientId

Käyttövalmis

AWS Lambda -toiminnon luominen

Tapaus 1: Välitä asiakastunnus X-AdobeSign-ClientId:ssä vastauksen otsakkeena

Tapaus 2: Välitä Client ID vastaustekstissä avaimella xAdobeSignClientId

AWS API -yhdyskäytävän määrittäminen

API-sovellusliittymän käyttöönotto

Käyttövalmis

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

Samanaikaisuuteen perustuva määrän rajoittaminen

Parhaat käytännöt

Muista seuraavat asiat...

JSON-kokorajoitus

Webhook-ilmoitukset

Yritä uudelleen, kun kuuntelupalvelu on alhaalla

Pyydä apua nopeammin ja helpommin

Kysy yhteisöltä

Ota yhteyttä