Přehled webhooků služby Acrobat Sign

Přehled

Webhook je uživatelem definovaná žádost protokolu HTTPS, která je aktivována, když se na zdrojovém webu (v tomto případě Adobe Acrobat Sign) vyskytne odebíraná událost.

Ve skutečnosti není webhook nic jiného než služba REST, která přijímá data nebo proud dat.

Webhooky jsou určeny ke komunikaci mezi službami v modelu PUSH (doručování bez vyžádání).

Když je aktivována odebíraná událost, služba Acrobat Sign vytvoří žádost HTTPS POST s tělem JSON a doručí ji na stanovenou adresu URL.

Před konfigurací webhooků se ujistěte, že vaše síť přijme rozsahy adres IP potřebné k fungování.

Webhooky nabízejí oproti předchozí metodě zpětného volání řadu výhod, mezi které mimo jiné patří:

• Správci mohou povolit webhooky, aniž by museli zahrnout podporu služby Acrobat Sign do vypisování adresy URL zpětného volání
• Webhooky jsou lepší z hlediska „čerstvosti“ dat, efektivity komunikace a zabezpečení. Není vyžadováno dotazování
• Webhooky umožňují snadno používat různé úrovně rozsahu (účet/skupina/uživatel/zdroj). 
• Webhooky představují modernější řešení rozhraní API, které umožňuje přímočařeji konfigurovat moderní aplikace
• Pro každý rozsah (účet/skupina/uživatel/zdroj) lze nakonfigurovat více webhooků, zatímco předchozí zpětná volání musela být jedinečná
• Webhooky umožňují provést výběr dat, která mají být vrácena, zatímco předchozí zpětná volání jsou řešení typu „všechno nebo nic“
• Metadata přenášená s webhookem lze konfigurovat (základní nebo podrobná)
• Webhooky lze podle potřeby snáze vytvářet, upravovat nebo deaktivovat, protože uživatelské rozhraní je zcela pod kontrolou správce.

Předpoklady

Aby služba fungovala, musíte povolit rozsahy adres IP pro webhooky prostřednictvím zabezpečení sítě.

Starší služba URL pro zpětné volání v REST v5 využívá stejné rozsahy IP jako služba webhook.

Jak se používá

Správci budou muset nejprve disponovat službou webhooku, která bude připravena přijímat příchozí nabídky ze služby Acrobat Sign. V tomto ohledu existuje mnoho možností, a dokud služba dokáže přijímat požadavky POST a GET, bude webhook úspěšný.

Jakmile je služba zavedena, může správce služby Acrobat Sign vytvořit nový webhook z rozhraní Webhook v nabídce Účet na webu služby Acrobat Sign.

Správci mohou nakonfigurovat webhook pro aktivaci událostí Dohoda, Webový formulář (Widget) nebo Hromadné odeslání (MegaSign). Prostřednictvím rozhraní API lze nakonfigurovat také zdroj šablony knihovny (dokumentu knihovny).

Rozsah webhooku může zahrnovat celý účet nebo jednotlivé skupiny prostřednictvím rozhraní správce. Rozhraní API umožňuje dosáhnout větší míry podrobnosti prostřednictvím výběru rozsahu UŽIVATEL nebo ZDROJ.

Typ dat, která jsou odesílána na adresu URL, je konfigurovatelný a může zahrnovat položky, jako jsou Informace o dohodě, Informace o účastníkovi, Informace o dokumentu atd.

Jakmile je webhook nakonfigurován a uložen, služba Acrobat Sign odešle nový objekt JSON na definovanou adresu URL pokaždé, když dojde k aktivaci odebírané události. Pokud nechcete změnit aktivační kritéria události nebo datovou část JSON, není vyžadována žádná průběžná manipulace s webhookem.

Ověření záměru adresy URL webhooku

Před úspěšnou registrací webhooku služba Acrobat Sign ověří, zda adresa URL webhooku, která je uvedena v žádosti o registraci, zamýšlí přijímat oznámení, nebo nikoli. Za tímto účelem služba Acrobat Sign po obdržení nové žádosti o registraci webhooku nejprve požádá o ověření adresy URL webhooku. Tato žádost o ověření je odeslána na adresu URL webhooku ve formě požadavku HTTPS GET. Tento požadavek má vlastní hlavičku HTTP X-AdobeSign-ClientId. Hodnota v této hlavičce je nastavena na ID klienta (ID aplikace) aplikace API požadující vytvoření/registraci webhooku. K dosažení úspěšné registrace webhooku musí adresa URL webhooku odpovědět na žádost o ověření kódem odpovědi 2XX A navíc MUSÍ odeslat zpět stejnou hodnotu ID klienta jedním z následujících dvou způsobů:

• Buď v hlavičce odpovědi X-AdobeSign-ClientId. Jedná se o stejnou hlavičku, která byla předána v požadavku, a nyní bude vrácena v odpovědi.
• Nebo v těle odpovědi JSON pomocí klíče xAdobeSignClientId, jehož hodnota se shoduje s ID klienta odeslaným v požadavku.

Webhook bude úspěšně zaregistrován pouze při úspěšné odpovědi (kódu odpovědi 2XX) a ověření ID klienta buď v hlavičce, nebo v těle odpovědi. Účelem této žádosti o ověření je prokázat, že adresa URL webhooku chce přijímat oznámení na této adrese URL. Pokud byste omylem zadali nesprávnou adresu URL, adresa URL by neodpověděla správně na požadavek ověření záměru a služba Acrobat Sign by na tuto adresu URL nezasílala žádná oznámení. Kromě toho může adresa URL webhooku také potvrdit, že bude přijímat oznámení pouze prostřednictvím webhooků registrovaných konkrétní aplikací. To lze provést ověřením ID klienta aplikace předaného v hlavičce X-AdobeSign-ClientId. Pokud adresa URL webhooku nerozpozná toto ID klienta, NESMÍ odpovědět kódem úspěšné odpovědi a služba Acrobat Sign zajistí, aby tato adresa URL nebyla zaregistrována jako webhook.

Ověření volání adresy URL webhooku se provede v následujících situacích:

• Registrace webhooku: Pokud toto ověření volání adresy URL webhooku selže, webhook nebude vytvořen.
• Aktualizace webhooku ze stavu NEAKTIVNÍ na stav AKTIVNÍ: Pokud toto ověření volání adresy URL webhooku selže, stav webhooku nebude změněn na AKTIVNÍ.

Jak reagovat na oznámení webhooku

Služba Acrobat Sign provádí implicitní ověření záměru v každém požadavku na oznámení webhooku odeslaném na adresu URL webhooku. Každý požadavek HTTPS na oznámení webhooku proto obsahuje také vlastní hlavičku HTTP s názvem X-AdobeSign-ClientId. Hodnotou této hlavičky je ID klienta (ID aplikace) aplikace, která webhook vytvořila. Oznámení webhooku bude považováno za úspěšně doručené pouze v případě, že bude vrácena úspěšná odpověď (kód odpovědi 2XX) a bude odesláno ID klienta buď v hlavičce HTTP (X-AdobeSign-ClientId), nebo v těle odpovědi JSON pomocí klíče xAdobeSignClientId, přičemž bude shodné s ID klienta z požadavku, jinak se budeme snažit doručit oznámení na adresu URL webhooku až do vyčerpání přípustného počtu opakování.

Postup povolení nebo zakázání

Přístup k funkci Webhooky je ve výchozím nastavení povolen pro účty podnikové úrovně.

Správci na úrovni skupiny mohou vytvářet a ovládat webhooky, které fungují pouze v rámci jejich skupiny.

Přístup ke stránce Webhooky získáte na levé liště nabídky Správce.

Omezení rychlosti na základě souběžnosti

Události vytváření a oznámení webhooků (a zpětných volání) jsou omezeny počtem souběžných oznámení, která jsou aktivně doručována zákazníkovi ze systému Acrobat Sign. Tento limit se vztahuje na účet a zahrnuje všechny skupiny v rámci účtu.
Tento typ omezení rychlosti zabraňuje tomu, aby jeden špatně navržený účet spotřebovával neúměrné množství zdrojů serveru, což by mělo negativní dopad na všechny ostatní zákazníky v daném serverovém prostředí.

Počet souběžných událostí na účet byl vypočten tak, aby bylo zajištěno, že účty s dobře ošetřenými webhooky budou dostávat svá oznámení v co nejkratší době a jen zřídka by se měly setkat se situací, kdy se oznámení zpozdí kvůli příliš velkému počtu požadavků. Aktuální prahové hodnoty jsou:

Osvědčené postupy

• Přihlaste se k odběru konkrétních potřebných událostí, abyste omezili počet požadavků protokolu HTTPS na server – Čím konkrétněji můžete webhooky nastavit, tím menší objem budete muset procházet.
• Vyvarujte se duplicit – Pokud více aplikací sdílí stejnou adresu URL webhooku a stejný uživatel je namapován na každou z těchto aplikací, bude stejná událost odeslána do webhooku vícekrát (jednou pro každou aplikaci). V některých případech může webhook obdržet duplicitní události. Vaše aplikace webhooku by měla být na takovou situaci připravena a měla by duplicity odstraňovat podle ID události.
• Na webhooky reagujte vždy rychle – Vaše aplikace má na odpověď na požadavky webhooku k dispozici pouze pět sekund. V případě požadavku na ověření se jedná jen zřídka o problém, protože aplikace nemusí při odpovědi vykonávat žádnou skutečnou práci. V případě požadavků na oznámení však aplikace obvykle provádí nějaké úkony, takže odpověď na požadavek vyžaduje určitý čas. Je doporučeno pracovat v samostatném vlákně nebo asynchronně pomocí fronty, abyste měli jistotu, že stihnete odpovědět do pěti sekund
• Provádějte správu souběžnosti – Pokud uživatel provede několik změn v rychlém sledu za sebou, aplikace pravděpodobně obdrží zhruba ve stejnou dobu více oznámení pro stejného uživatele. Pokud si nedáte pozor na způsob správy souběžnosti, vaše aplikace může v konečném důsledku zpracovávat stejné změny pro stejného uživatele vícekrát. Chcete-li využívat výhody poskytované webhooky služby Acrobat Sign, je nezbytné porozumět tomu, jak používají informace. Nezapomeňte si položit otázky, jako například:
  • Jaká data chcete vracet v datové části?
  • Kdo bude přistupovat k těmto informacím?
  • Jaká rozhodnutí nebo hlášení budou generována?
• Doporučení pro přijetí podepsaného dokumentu – Při určování způsobu přijetí podepsaného dokumentu PDF ze služby Acrobat Sign do systému správy dokumentů je nutné zvážit několik faktorů.

Přestože je zcela přijatelné při vytváření webhooku pouze vybrat možnost Podepsaný dokument dohody, můžete zvážit použití rozhraní API služby Acrobat Sign k načtení dokumentů při přijetí aktivační události (jako je stav dohody Dokončeno).

Na co pamatovat...

Omezení velikosti JSON

Velikost datové části JSON je omezena na 10 MB.

Pokud událost vygeneruje větší datovou část, webhook bude aktivován, ale atributy podmíněného parametru, pokud se v požadavku vyskytují, budou odebrány, aby se zmenšila velikost datové části. 

Pokud k tomu dojde, bude v odpovědi vrácen objekt „ConditionalParametersTrimmed“, který klienta upozorní na odebrání informací conditionalParameters.

„conditionalParametersTrimmed“ je objekt typu pole obsahující informace o oříznutých klíčích.

Zkrácení bude provedeno v následujícím pořadí:

• includeSignedDocuments
• includeParticipantsInfo
• includeDocumentsInfo
• includeDetailedInfo

Zkráceny budou nejprve podepsané dokumenty, poté informace o účastníkovi, informace o dokumentu, a nakonec podrobné informace.

K tomu může dojít například při události dokončení dohody, pokud obsahuje také podepsaný dokument (v kódu base 64), nebo u dohody s více poli formuláře

Oznámení webhooku

Webhooky služby Acrobat Sign doručují oznámení odesílateli dohody a všem webhookům nakonfigurovaným ve skupině, ze které byla dohoda odeslána. Webhooky s rozsahem účtu přijímají všechny události.

Opakování, když je naslouchající služba nefunkční

Pokud je cílová adresa URL webhooku z jakéhokoli důvodu nefunkční, služba Acrobat Sign zařadí objekt JSON do fronty a opakuje pokus o odeslání v postupném cyklu po dobu 72 hodin.

Nedoručené události zůstanou ve frontě opětovných pokusů a v následujících 72 hodinách bude vynaloženo maximální úsilí na doručení oznámení v pořadí, v jakém k nim došlo.

Strategie opakování doručení upozornění spočívá ve zdvojnásobování prodlevy mezi jednotlivými pokusy. Začíná se minutovým intervalem, který se postupně zvyšuje na 12 hodin, ve výsledku tedy 15 opakování za 72 hodin.

Pokud přijímač webhooku neodpoví do 72 hodin a v posledních sedmi dnech nedošlo k žádnému úspěšnému doručení oznámení, bude webhook deaktivován. Na tuto adresu URL nebudou zasílána žádná oznámení, dokud nebude webhook znovu aktivován.

Všechna oznámení v době mezi deaktivací webhooku a jeho následnou opětovnou aktivací budou ztracena.