Näyte Javascript-koodista, jolla haetaan asiakkaan tunnus, validoidaan se ja palautetaan se vastausotsikkoon
Päivitetty viimeksi
4. tammikuuta 2024
|
Koskee myös seuraavaa Adobe Acrobat Sign
- Adobe Acrobat Sign -integraatiot
- Uudet ominaisuudet
- Tuotteen versiot ja elinkaari
- Acrobat Sign for Salesforce
- Asenna paketti
- Määritä paketti
- Käyttöopas
- Ota käyttöön digitaalinen todennus
- Kehittäjän opas
- Edistyneen mukautuksen opas
- Kenttien vastaavuusmääritys- ja malliopas
- Mobiilisovelluksen käyttöopas
- Työnkulkujen automatisointiopas
- Document Builder -opas
- Suurten asiakirjojen määrittäminen
- Päivitysopas
- Julkistustiedot
- UKK:t
- Vianmääritysopas
- Muut artikkelit
- Acrobat Sign for Microsoft
- Acrobat Sign for Microsoft 365
- Acrobat Sign for Outlook
- Acrobat Sign for Word/PowerPoint
- Acrobat Sign for Teams
- Acrobat Sign for Microsoft PowerApps and Power Automate
- Acrobat Sign Connector for Microsoft Search
- Acrobat Sign for Microsoft Dynamics
- Acrobat Sign for Microsoft SharePoint
- Yleiskatsaus
- SharePoint On-Prem: Asennusopas
- SharePoint On-Prem: Mallien vastaavuusmääritysopas
- SharePoint On-Prem: Käyttöopas
- SharePoint On-Prem: Julkaisutiedot
- SharePoint Online: Asennusopas
- SharePoint Online: Mallien vastaavuusmääritysopas
- SharePoint Online: Käyttöopas
- SharePoint Online: Verkkolomakkeiden vastaavuusmääritysopas
- SharePoint Online: Julkaisutiedot
- Acrobat Sign for Microsoft 365
- Acrobat Sign for ServiceNow
- Acrobat Sign for HR ServiceNow
- Acrobat Sign for SAP SuccessFactors
- Acrobat Sign for Workday
- Acrobat Sign for NetSuite
- Acrobat Sign for SugarCRM
- Acrobat Sign for VeevaVault
- Acrobat Sign for Coupa BSM Suite
- Acrobat Sign for Zapier
- Acrobat Sign -kehittäjädokumentaatio
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.
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ä:
Käyttötapa
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
|
|
|---|
|
// 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; } |
|
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:
- Välitä X-AdobeSign-ClientId vastauksen otsikkeessa. Se on sama otsake, joka välitettiin pyynnössä, ja se on toistettava vastauksessa.
|
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"); } } |
- 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.
Määritysasetukset
Webhook-sovelluksen määrittäminen edellyttää viiden elementin määrittelyä:
- Nimi– on syytä käyttää selkeää nimeä, jonka muut ylläpitäjät ymmärtävät helposti.
- Käyttöalue - Kuinka isolla verkolla webhook pyydystää? Tili ja Ryhmä ovat saatavana käyttöliittymässä.
- API tukee Tili-, Ryhmä-, Käyttäjä- ja Resurssi-käyttöalueita.
- Yhtä webhookia kohti voi määrittää vain yhden käyttöalueen.
- URL - Kohteen URL-osoite, johon Acrobat Sign on työntänyt JSON-kuorman.
- Tapahtumat - Käynnistin, joka saa Acrobat Signin luomaan JSON:in ja työntämään sen URL-osoitteeseen.
- Jokainen tapahtuma luo laukaisutapahtuman kannalta merkityksellisen hyötykuorman.
- Yksi webhook voi sisältää monta tapahtumaa.
- Ilmoitusparametrit - Ilmoitusparametrit yksilöivät tapahtuman JSON-hyötykuorman osiot, jolloin voit valita vain ne tapahtuman osiot, jotka ovat kyseiselle webhookille tärkeitä (mikä vähentää tarpeettomien tietojen lähettämistä URL-osoitteeseen).
Kun webhook on määritetty kokonaan, valitse Tallenna, niin uusi webhook alkaa välittömästi reagoida laukaisutapahtumiin.
Huomautus:
Määritä webhookin URL-osoite vastaamaan webhookin vahvistus- ja webhookin ilmoituspyyntöihin yllä kuvatun vahvistuskäytännön mukaisesti. Acrobat Sign -verkkosovelluksesta luotuihin webhookeihin lähetettävä asiakastunnus (sovellustunnus) on - UB7E5BXCXY
Käyttöalueet
- Tili: Kaikki tilillä tehdyt tilaustapahtumat käynnistävät työnnön.
- Tilin ylläpitäjillä on valtuudet nähdä kaikki tilille ja tilin ryhmille määritetyt webhookit.
- Ryhmä: Kaikki ryhmässä tilatut tapahtumat käynnistävät työnnön. HUOM.: Ryhmän laajuiset webhookit ovat olemassa vain kyseiselle ryhmälle.
- Ryhmien ylläpitäjät näkevät vain oman ryhmänsä webhookit. He eivät näe tilitason webhookeja tai muihin ryhmiin sidottuja webhookeja.
- Tilit, joilla Käyttäjiä useissa ryhmissä -toiminto on käytössä, näkevät vaihtoehdon, jolla voidaan määrittää ryhmä, johon käyttöaluetta sovelletaan.
- Käyttäjätili: Kaikki käyttäjätilin tilatut tapahtumat laukaisevat vaatimuksen. Käyttäjätason webhookit voidaan luoda vain API: n kautta.
- Resurssitason webhook: Tämä luodaan tiettyä resurssia varten. Tähän resurssiin liittyvät tapahtumat siirretään webhookin URL-osoitteeseen. Resurssitason webhookit voidaan luoda vain API:n kautta.
URL
Webhook URL-osoite on palvelin, joka kuuntelee saapuvia HTTPS POST -ilmoitusviestejä, jotka laukeavat tapahtumien sattuessa.
Tarvitset tämän URL-osoitteen tilataksesi webhookisi tapahtumiin.
- Asiakkaan on sisällytettävä HTTPS-URL-osoite, johon Acrobat Sign voi käyttää POST-metodia. Tämän URL-osoitteen on oltava käytettävissä julkisessa verkossa.
- Esimerkiksi 127.0.0.1 ja paikalliset isäntä-URI-tunnisteet eivät toimi.
- URL-päätepisteen on kuunneltava porttia 443 tai 8443 (asiakas päättää asiasta, kun vastakutsun URL-osoitetta määritetään).
- Varmista, että webhook tukee POST-pyyntöjä saapuville tapahtumailmoituksille ja GET-pyyntöjä vahvistuspyynnöille.
- Palomuuri ei saa estää URL-osoitetta.
Alla on tapahtumia, jotka voivat käynnistää viennin webhookin URL-osoitteeseen. Ne on ryhmitelty objektin mukaan ja lueteltu käyttöliittymän mukaisessa järjestyksessä.
Vasemmalla on arvo, jonka näet Acrobat Signin käyttöliittymässä. Oikealla oleva arvo on webhookin nimi API:ssa.
Täydelliset tiedot webhookeista ja niiden hyötykuormista löytyvät Acrobat Signin kehittäjäoppaasta.
Sopimukset:
| Käyttöliittymäelementti | Webhookin nimi |
| Sopimus, kaikki tapahtumat | AGREEMENT_ALL |
| Sopimus on luotu | AGREEMENT_CREATED |
| Sopimus lähetetty | AGREEMENT_ACTION_REQUESTED |
| Sopimuksen osallistuja on valmis | AGREEMENT_ACTION_COMPLETED |
| Sopimuksen työnkulku on suoritettu | AGREEMENT_WORKFLOW_COMPLETED |
| Sopimus on vanhentunut | AGREEMENT_EXPIRED |
| Sopimus on poistettu | AGREEMENT_DOCUMENTS_DELETED |
| Sopimus on peruutettu | AGREEMENT_RECALLED |
| Sopimus on hylätty | AGREEMENT_REJECTED |
| Sopimus on jaettu | AGREEMENT_SHARED |
| Sopimus on delegoitu | AGREEMENT_ACTION_DELEGATED |
| Sopimuksen osallistuja on korvattu | AGREEMENT_ACTION_REPLACED_SIGNER |
| Sopimusta on muutettu | AGREEMENT_MODIFIED |
| Sopimuksen muutos on kuitattu | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
| Sopimussähköpostiviestiä on tarkasteltu | AGREEMENT_EMAIL_VIEWED |
| Sopimussähköpostiviestin toimitus epäonnistui | AGREEMENT_EMAIL_BOUNCED |
| Sopimuksen luonti epäonnistui | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Sopimus on synkronoitu offline-tapahtuman jälkeen | AGREEMENT_OFFLINE_SYNC |
| Lähettäjä on ladannut sopimuksen palvelimelle | AGREEMENT_UPLOADED_BY_SENDER |
| Sopimus on tallennettu säilöön | AGREEMENT_VAULTED |
| Sopimukseen osallistujan henkilöllisyys on todennettu | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
| Sopimuksen osallistuja on todennettu tietoon perustuvalla todennuksella | AGREEMENT_KBA_AUTHENTICATED |
| Sopimusmuistutus on lähetetty | AGREEMENT_REMINDER_SENT |
| Allekirjoittaja on muuttanut sopimuksen allekirjoittajan nimeä | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
| Sopimuksen webhookit ovat saatavana vain API:n kautta | |
| PUUTTUU | AGREEMENT_EXPIRATION_UPDATED |
| PUUTTUU |
AGREEMENT_READY_TO_NOTARIZE |
| PUUTTUU |
AGREEMENT_READY_TO_VAULT |
Erälähetys:
| Käyttöliittymäelementti | Webhookin nimi |
| Erälähetä kaikki tapahtumat | MEGASIGN_ALL |
| Erälähetys luotu |
MEGASIGN_CREATED |
| Erälähetys jaettu |
MEGASIGN_SHARED |
| Erälähetys peruttu |
MEGASIGN_RECALLED |
Verkkolomakkeet:
| Käyttöliittymäelementti | Webhookin nimi |
| Verkkolomake kaikki tapahtumat | WIDGET_ALL |
| Verkkolomake on luotu. |
WIDGET_CREATED |
| Verkkolomake on otettu käyttöön |
WIDGET_ENABLED |
| Verkkolomake on poistettu käytöstä |
WIDGET_DISABLED |
| Verkkolomaketta on muutettu |
WIDGET_MODIFIED |
| Verkkolomake on jaettu |
WIDGET_SHARED |
| Verkkolomakkeen luonti epäonnistui |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Kirjastomallit (vain API):
| Käyttöliittymäelementti | Webhookin nimi |
| PUUTTUU | LIBRARY_DOCUMENT_ALL |
| PUUTTUU | LIBRARY_DOCUMENT_CREATED |
| PUUTTUU | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| PUUTTUU | LIBRARY_DOCUMENT_MODIFIED |
Ilmoitusparametrit
Ilmoitusparametrien avulla voit mukauttaa JSON-hyötykuorman vain tiettyihin tapahtuman elementteihin.
Esimerkiksi Sopimuksen osallistuja korvattu -tapahtumassa saatat haluta säilyttää vain Sopimustiedot ja Osallistujatiedot ja jättää pois Asiakirjatiedot, mikä vähentää Webhook URL-osoitteeseen lähetetyn JSON:in kokoa.
- Sopimus
- Sopimustiedot - Yksityiskohtaiset sopimustiedot, jotka perustuvat siihen tilaan, missä sopimus on käynnistävän tapahtuman aikana.
- Sopimusasiakirjan tiedot - Sisältää kaikki tapahtuman tuloksena syntyneet asiakirjatiedot.
- Sopimuksen osallistujan tiedot - Sisältää kaikki tapahtuman tuloksena syntyneet osallistujan tiedot.
- Sopimuksen allekirjoitettu dokumentti - Antaa allekirjoitetun PDF-tiedoston.
- Soveltuu Sopimuksen työnkulku valmis- ja Sopimus kaikki -tapahtumiin.
- Erälähetys
- Erälähetyksen tiedot - Yksityiskohtaiset tiedot tapahtuman käynnistäneestä erälähetysobjektista.
- Verkkolomake
- Widgetin tiedot – Yksityiskohtaiset tiedot tapahtuman laukaisseesta verkkolomakkeesta.
- Pienoissovelluksen asiakirjatiedot - Verkkolomakkeeseen liittyvät asiakirjatiedot.
- Pienoissovelluksen osallistujatiedot - Tietoja verkkolomakkeen osallistujista.
Kaksisuuntainen SSL-todennus
Kaksisuuntainen SSL, jota kutsutaan usein asiakaspuolen SSL:ksi tai yhteiseksi TLS:ksi, on SSL-tila jossa sekä palvelin että asiakas (verkkoselain) esittävät varmenteita tunnistautuakseen.
Tilin ylläpitäjät voivat määrittää asiakaspuolen varmenteen Suojausasetukset-sivulla.
Acrobat Sign vahvistaa SSL-varmenteet toimittaessaan kuormia webhookin URL-osoitteeseen. SSL-varmenteen tarkastuksessa epäonnistuneet webhookit eivät toimita JSON-hyötykuormaa.
Todenna kaksisuuntaisella SSL:llä asiakas (Acrobat Sign) ja kuuntelupalvelu varmistaaksesi, että vain Acrobat Sign pääsee webhookisi URL-osoitteeseen.
Jos webhook on luotu kumppanisovelluksella, se käyttää kumppanisovelluksen tilin asiakasvarmennetta (jos se on saatavilla) tunnistautumiseen webhook-kutsuja lähettäessään.
Alla on esitetty yleisimmät kysymykset sekä verkkopalvelimen varmennusprosessista että asiakkaan sertifioinnin varmennuksesta.
Verkkopalvelimen vahvistus
Webhookin rekisteröinnin aikana Acrobat Sign vahvistaa webhook-palvelimen URL-osoitteen.
Asiakkaat eivät pysty rekisteröimään webhookia, jos Acrobat Signistä ei voida toteuttaa yhteyttä webhookin vastakutsun URL-osoitteeseen.
Ei.
Webhook-kutsun URL-osoite voi olla ainoastaan HTTPS portissa 443 tai 8443.
Acrobat Sign estää lähtevän HTTPS-liikenteen kaikkiin muihin portteihin.
Hyvä tapa varmistaa palvelimen varmenne on käyttää DigiCert ® SSL -asennuksen vianmääritystyökalua.
Riittää että syötät isäntänimen, kuten: www.digicert.com
Yleisiä kysymyksiä ovat:
- Ongelma: epäluotettavan CA-varmenteen tai itse allekirjoitetun varmenteen käyttäminen
Korjaus: Käytä julkista CA:n myöntämää SSL-sertifikaattia webhookin vastakutsun palvelimelle.
- Ongelma: Palvelin ei lähetä välivarmennetta
Korjaus: Asenna välivarmenteet webhookin vastakutsupalvelimeen.
Lisätietoja löytyy osoitteesta https://www.digicert.com/kb/ssl-certificate-installation.htm.
Asiakasvarmenteen varmennus
Jos haluat määrittää kaksisuuntaisen SSL:n webhookille, vaadimme hallinnoijaa lataamaan palvelimelle yksityisen avaimen sisältävän .p12- (tai .pfx-) tiedoston. Tiedosto tallennetaan turvallisesti asiakastilille, ja hallinnoija voi poistaa sen milloin tahansa.
Kaksisuuntaisessa webhook-asetuksessa Acrobat Sign on kutsuja/asiakas ja tarvitsee yksityisen avaimen todistaakseen, että Acrobat Sign tekee kutsun asiakastilin puolesta.
-
Varmista, että kaksisuuntainen SSL on käytössä
Kaksisuuntaisen SSL:n on oltava käytössä webhookin vastakutsupalvelimella.
Voit yhdistää webhookin vastakutsun URL-osoitteeseen millä tahansa selaimella. Sinun pitäisi saada:
400 virheellinen pyyntö Vaadittua SSL-sertifikaattia ei lähetetty
Tämä tarkoittaa, että palvelin odottaa asiakkaan lähettävän asiakkaan varmenteet (eli palvelimelle on otettu käyttöön kaksisuuntainen SSL).
Jos et näe yllä olevaa viestiä, kaksisuuntainen SSL ei ole käytössä.
Huomautus:Voit käyttää Postmania, ja tehdä POST-pyynnön webhookin vastakutsun URL-osoitteeseen. Sinun pitäisi saada samankaltainen tulos.
-
Asiakkaan tunnistetiedot voivat olla joko itse allekirjoitettu sertifikaatti tai CA:n myöntämä sertifikaatti. Sen on kuitenkin oltava vähintään seuraavien X.509 v3 -laajennusten vaatimusten mukainen:
X.509 v3 -laajennus
Arvo
ExtendedKeyUsage
clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
Asiakkaan varmenteen on oltava PKCS12-tiedosto, jonka tunniste on .p12 tai .pfx, ja sen on sisällettävä sekä asiakkaan varmenne (jotta palvelin voi tarkistaa asiakkaan henkilöllisyyden) että asiakkaan yksityinen avain (jotta asiakas voi digitaalisesti allekirjoittaa viestejä palvelimelle SSL-kättelyn aikana varmistettavaksi).
Käytä komentoa openssl p12 (pfx) -tiedoston varmistamiseksi:
openssl pkcs12 -info -in outfile.p12
Yksityisen avaimen tunnuslausetta pitäisi vaatia. Tulosteessa tulisi olla sekä varmenteita että salattu yksityinen avain, kuten:
Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 -----BEGIN CERTIFICATE----- MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE ... JAKQLQ== -----END CERTIFICATE----- Bag Attributes: <No Attributes> subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA -----BEGIN CERTIFICATE----- MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3 ... -----END CERTIFICATE----- Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB Key Attributes: <No Attributes> -----BEGIN ENCRYPTED PRIVATE KEY----- MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA ... FHE= -----END ENCRYPTED PRIVATE KEY-----Varmenteen tulisi sisältää vähintään valtuutusvarmenne ja välivaiheen varmenteet. Ihannetapauksessa se sisältää myös root CA -varmenteen.
Hälytys:Varmista, että .p12- tai .pfx-tiedosto on suojattu salasanalla.
-
Luo itse allekirjoitettu asiakassertifikaatti (valinnainen)
Asiakkaan varmenteet voivat olla joko CA:n myöntämiä tai itse allekirjoitettuja tarpeestasi riippuen.
Luo itse allekirjoitettu asiakassertifikaatti käyttämällä seuraavaa openssl-komentoa:
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Varoitus:Pidä tuloksena luodut tiedostot salassa, koska ne ovat itse allekirjoitetut CA-varmenteesi.
Luo seuraavaksi client .p12 -tiedosto:
- Luo yksityinen avain SSL-asiakkaalle:
openssl genrsa -out client.key 2048
- Luo varmennepyyntö asiakkaan yksityisellä avaimella:
openssl req -new -key client.key -out client.req
- Myönnä asiakkaan varmenne käyttäen varmennepyyntöä ja CA-varmennetta/avainta:
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Muunna asiakkaan varmenne ja yksityinen avain selaimia varten pkcs#12-formaattiin:
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Poista asiakkaan yksityinen avain, asiakkaan varmenne ja asiakkaan pyyntötiedostot, koska pkcs12:ssa on kaikki tarvitsemasi.
rm client.key client.cer client.req
- Luo yksityinen avain SSL-asiakkaalle:
-
- Käytä Postmania asiakkaan PFX-tiedoston lataamiseen siirtymällä kohtaan Asetukset > Varmenteet.
- Lisää asiakkaan varmenne valitsemalla Lisää varmenne.
- Määritä HTTP-otsikko x-adobesign-clientid:lle:
Kun määritys on tehty, lähetä POST-pyyntö webhookin vastakutsun URL-osoitteeseen.
Sinun pitäisi saada 200-vastaus.
-
Miksi Acrobat Sign hylkää PFX-tiedostoni, vaikka olen vahvistanut sen Postmanissa?
Jos olet noudattanut edellä mainittua prosessia pfx-tiedoston todentamisessa, ja Acrobat Sign hylkää pfx-tiedoston edelleen, on todennäköistä, että tiedosto on luotu Microsoft-työkalulla, joka pystyy luomaan epätyypillisen PKCS12-tiedoston.
Tässä tapauksessa käytä alla olevia openssl-komentoja purkaaksesi varmenteet ja yksityisen avaimen pfx-tiedostosta, ja luo sitten oikein muotoiltu PKCS12-tiedosto:
// Pura varmenteet ja yksityinen avain pfx-tiedostosta openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.crt -nokeys openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.key -nodes -nocerts // Luo uusi PKCS12-tiedosto openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Käyttöönotto tai poistaminen käytöstä
Webhooks-ominaisuuteen pääsy on oletuksena käytössä Enterprise-suunnitelman 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: Tili > Webhooks
Aktivoi webhook
Kun webhook luodaan ensikerran, se luodaan aktiivisessa tilassa.
Acrobat Signin Webhooks-sivulla näkyvät aktiiviset webhookit oletusarvoisesti.
Aktivoi passiivinen webhook seuraavasti:
- Napsauta Asetukset -kuvaketta (kolme vaakasuoraa viivaa) webhookien otsikkorivin oikealla puolella ja valitse Näytä kaikki Webhookit
- Valitse passiivinen webhook napsauttamalla sitä kerran.
- Tämä näyttää webhookin asetukset otsikkorivin alapuolella
- Valitse Aktivoi
Aktiivinen webhook aloittaa tietojen lähettämisen kohteen URL-osoitteeseen heti, kun seuraava tapahtuma on käynnistetty.
Poista webhookin aktivointi
Webhookin deaktivointi edellyttää vain, että
- Siirry Webhookit-sivulle.
- Napsauta kerran webhookia, jonka aktivoinnin haluat poistaa
- Valitse otsikkorivin alapuolella olevista valikkokohdista Poista aktivointi
- Kun webhookista on poistettu aktivointi, sen tilaksi tulee Passiivinen
Tarkastele tai muokkaa webhookia
Webhookeja voidaan muokata ja tallentaa milloin tahansa, ja tallennettaessa uuden määrityksen muutos tulee voimaan välittömästi.
Vain tapahtuma- ja ilmoitusparametreja voidaan muokata.
Jos nimeä, laajuutta tai URL-osoitetta on muutettava, on luotava uusi webhook.
Voit muokata webhookin parametreja seuraavasti:
- Siirry Webhookit-sivulle
- Napsauta kerran webhookia, jota haluat muokata
- Napsauta otsikkorivin alla olevaa Näytä/muokkaa -vaihtoehtoa
- Ota käyttöön kaikki tarvittavat muutokset ja valitse Tallenna
Poista webhook
Webhook voidaan poistaa milloin tahansa.
Webhookin poistaminen tuhoaa sen järjestelmässä, joten poistettua webhookia ei voi palauttaa.
Webhookeista ei tarvitse poistaa aktivointia ensin.
Voit poistaa webhookin seuraavasti:
- Siirry Webhookeihin
- Valitse poistettava webhook yhdellä napsautuksella
- Napsauta otsikkorivin alla olevaa Poista -vaihtoehtoa.
- Haaste esitetään varmistuksena siitä, että haluat poistaa webhookin. napsauta OK
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, jotka koskevat kaikkia sopimuksen osapuolia, jos kyseiselle käyttäjälle, heidän ryhmälleen tai heidän tililleen on määritetty webhook.
Sopimustilanteet käsitellään siten, että jos tapahtuman osallistujalle on määritetty webhook, kyseisen webhookin URL-osoitteeseen lähetetään ilmoitus. Toisin sanoen, webhookit laukaistaan kaikkia sovellettavia sopimuksia koskevissa tapahtumissa, jopa niissä, jotka ovat konsernin tai tilin ulkopuolella, jossa webhook on määritetty.
Ilmoitukset toimitetaan vain niiden tapahtumien osalta, joihin osallistuja osallistuu. Esimerkiksi sopimuksen lähettäjä saa lähes jokaisen ilmoituksen, kun taas vastaanottajat saavat ilmoituksia vain siitä alkaen, kun he ovat osallistuneet sopimukseen, ja vain niistä tapahtumista, joihin he ovat osallistuneet.
Webhook-ilmoitukset noudattavat nykyistä Acrobat Signin todennus- ja näkyvyysmallia, mikä tarkoittaa, että käyttäjät voivat käyttää sopimusta vasta, kun käyttäjän osallistuminen sopimukseen on alkanut.
Lähettäjä lähettää sopimuksen allekirjoitettavaksi kolmelle allekirjoittajalle.
- Lähettäjät-tilille on määritetty WebhookX-tilitaso.
- Signer1 on saman tilin jäsen kuin lähettäjä, mutta eri ryhmässä, ja kyseiselle ryhmälle on määritetty WehbhookY.
- Signer2 on toisen tilin jäsen, ja Signer2-tilille on määritetty tilitaso WebhookZ.
- Signer3 on saman tilin jäsen kuin lähettäjä.
Lähettäjä lähettää sopimuksen: WebhookX laukaisee “Sopimus luotu”- ja “Sopimus lähetetty” -ilmoitukset, kun taas WebhookY laukaisee “Sopimus lähetetty” -ilmoituksen.
Signer1 allekirjoittaa: WebhookX laukaisee “Sopimusosapuoli valmis” ja “Sopimus lähetetty” -ilmoitukset, WebhookY laukaisee “Sopimusosapuoli valmis” -ilmoituksen ja WebhookZ laukaisee “Sopimus lähetetty” -ilmoituksen.
Signer2 allekirjoittaa: WebhookX laukaisee “Sopimusosapuoli valmis”- ja “Sopimus lähetetty” -ilmoitukset, kun taas WebhookZ lähettää “Sopimusosapuoli valmis” -ilmoituksen.
Signer3 allekirjoittaa: WebhookX laukaisee “Sopimusosapuoli valmis”- ja “Sopimuksen työnkulku valmis” -ilmoitukset, WebhookY laukaisee “Sopimuksen työnkulku valmis” -ilmoituksen ja WebhookZ laukaisee “Sopimuksen työnkulku valmis” -ilmoituksen.
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.
