Configure webhooks

Hledat

Přehled

Webhook je uživatelem definované zpětné volání protokolu HTTPS, které je aktivováno, když se na zdrojovém webu vyskytne určitá událost (v tomto případě Adobe Acrobat Sign).

Webhook ve skutečnosti není nic jiného než webová služba, která přijímá požadavky HTTPS POST ze zdroje. Webhook je tedy služba REST, která přijímá data nebo proud dat.

Webhooky slouží ke komunikaci mezi službami v modelu doručování bez vyžádání.

Když nastane aktivační událost, služba Acrobat Sign vytvoří požadavek HTTPS POST s tělem JSON a doručí jej na stanovenou adresu URL.

 

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

  • Správci mohou povolit vlastní 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 snáze 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.
Poznámka:

Tento dokument je primárně zaměřen na uživatelské rozhraní pro webhooky ve webové aplikaci Acrobat Sign (dříve Adobe Sign).

Vývojáři, kteří hledají podrobné informace o rozhraní API, je mohou nalézt zde:


Jak se to 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ář nebo Hromadné odeslání.

Rozsah webhooku může zahrnovat celý účet nebo jednotlivé skupiny prostřednictvím rozhraní správce. Rozsahy Uživatel a Zdroj je také možné používat prostřednictvím rozhraní API

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, Podepsaný dokument 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 zachycení aktivační 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, skutečně zamýšlí přijímat oznámení, nebo nikoli. Za tímto účelem služba Acrobat Sign při obdržení nového požadavku na 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, která požaduje vytvoření/registraci webhooku. K dosažení úspěšné registrace webhooku musí adresa URL webhooku odpovědět na požadavek 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, které bylo odesláno 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 skutečně 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ů, které jsou registrovány 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, který je odeslán 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í.

Jak bylo uvedeno výše pro hlavičku X-AdobeSign-ClientId, která je obsažena v každém požadavku na oznámení ze služby Sign, hodnota této hlavičky (ID klienta) by měla být v odpovědi zopakována jedním ze dvou způsobů:

1. Hlavička HTTP X-AdobeSign-ClientId a hodnota shodná s tímto ID klienta

Ukázka kódu v jazyku JavaScript pro načtení ID klienta, jeho ověření a následné vrácení v hlavičce odpovědi

// Fetch client id

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

 

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    //Return it in response header

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

    response.status = 200;  // default value

}

Ukázka kódu PHP pro načtení ID klienta, jeho ověření a následné vrácení v hlavičce odpovědi

 

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    //Return it in response header

   header("X-AdobeSign-ClientId:$clientid");

   header("HTTP/1.1 200 OK"); // default value

}

?>

 


2. Tělo odpovědi JSON s klíčem xAdobeSignClientId a hodnotou shodnou s ID klienta

Ukázka kódu v jazyku JavaScript pro načtení ID klienta, jeho ověření a následné vrácení v těle odpovědi

// Fetch client id

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

 

 

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Return Client Id in the body

                       };

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

    response.body = responseBody;

    response.status = 200;

}

Ukázka kódu PHP pro načtení ID klienta, jeho ověření a následné vrácení v těle odpovědi

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

   //Return it in response body

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

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

   echo json_encode($body);

   header("HTTP/1.1 200 OK"); // default value

}

?>

Ukázka těla odpovědi JSON

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Předpoklady

Budete potřebovat:

  1. Účet Microsoft s licencí pro vytváření aplikací Azure Functions
  2. Existující aplikaci Azure Function, kterou můžete vytvořit podle pokynů uvedených na adrese https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function
  3. Základní znalost jazyka JavaScript, abyste dokázali pochopit a napsat kód v libovolném jazyce podle svého výběru


Postup vytvoření aktivační události pro Azure Functions, která slouží jako webhook služby Acrobat Sign

Vytvoření funkce Aktivační událost HTTP v jazyku JavaScript:

1. Přihlaste se prostřednictvím účtu Microsoft https://portal.azure.com/

2. Otevřete aplikaci Azure Function zobrazenou na kartě Aplikace funkcí.

Tím otevřete seznam aplikací Azure Function:

3. Vyberte aplikaci, ve které chcete vytvořit tuto novou funkci

4. Klikněte na tlačítko Vytvořit (+) a vytvořte novou funkci Azure

 

5. Vyberte možnost Webhook + API jako scénář a možnost JavaScript jako jazyk

6. Klikněte na tlačítko Vytvořit tuto funkci

Vytvoří se nová funkce, která dokáže zpracovat příchozí požadavek rozhraní API.


Přidání logiky pro registraci webhooku služby Acrobat Sign

Před úspěšnou registrací webhooku služba Acrobat Sign ověří, zda adresa URL webhooku, která je uvedena v žádosti o registraci, skutečně zamýšlí přijímat oznámení, nebo nikoli. Za tímto účelem služba Acrobat Sign při obdržení nového požadavku na 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 s vlastní hlavičkou HTTP X-AdobeSign-ClientId. Hodnota v tomto záhlaví je nastavena na ID klienta aplikace, která požaduje vytvoření/registraci webhooku. K dosažení úspěšné registrace webhooku musí adresa URL webhooku odpovědět na požadavek 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ů.

K dispozici jsou dvě možnosti, jak můžete pokračovat:


Možnost 1: Předání ID klienta v X-AdobeSign-ClientId jako hlavičce odpovědi

Předejte X-AdobeSign-ClientId v hlavičce odpovědi. Jedná se o stejnou hlavičku, která byla předána v požadavku, a musí být vrácena v odpovědi.

Nahraďte kód souboru Index.js následujícím kódem:

module.exports = function (context, req) {

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

    // Validate that the incoming ClientID is genuine

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: "Notification Accepted",

            headers : {

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

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Vyzkoušejte chování napodobením požadavku:

1. Klikněte na tlačítko Test v pravém rohu

2. Vytvořte fiktivní požadavek

Hlavičky odpovědí se sice výše nezobrazují, ale můžete je sledovat prostřednictvím napodobování pomocí aplikace Postman, DHC nebo nebo jiné služby.


Možnost 2: Předání ID klienta v těle odpovědi pomocí klíče xAdobeSignClientId

Předejte ID klienta v těle odpovědi JSON pomocí klíče xAdobeSignClientId, jehož hodnota se shoduje s ID klienta, které bylo zasláno v hlavičce požadavku.

Nahraďte kód souboru Index.js následujícím kódem:

module.exports = function (context, req) {

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

    // Validate that the incoming ClientID is genuine

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

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Vyzkoušejte chování napodobením požadavku

1. Klikněte na tlačítko Test v pravém rohu

2. Vytvořte fiktivní požadavek

Všimněte si také, že stejné chování pro ID klienta je očekáváno, když adresa URL webhooku přijme oznámení POST. 


Připraveno k použití

Po ověření chování je adresa URL webhooku funkční podle standardů služby Acrobat Sign. Dále můžete aktualizovat vlastní logiku podle svých požadavků.

 

Získání adresy URL funkce

  • Klikněte na možnost Získat adresu URL funkce

 

Zkopírujte adresu URL a použijte ji k vytvoření webhooků ve službě Acrobat Sign.

Vytvoření funkce AWS Lambda

Chcete-li vytvořit funkci AWS Lambda, přihlaste se do konzoly pro správu AWS a v seznamu služeb vyberte službu AWS Lambda.

  • Klikněte na možnost Vytvořit funkci Lambda pomocí možnosti „Vytvořit zcela od začátku“
  • Na stránce Konfigurovat funkci zadejte název funkce „lambdaWebhooks“ a jako modul runtime vyberte možnost Node.js 4.3
  • Pro položku Role vyberte existující roli nebo vytvořte novou roli ze šablon(y)
    • Pokud jste vybrali možnost Vytvořit novou roli ze šablon(y), zadejte název role (např. role-lambda) a ze seznamu Šablony zásad vyberte možnost Oprávnění jednoduchých mikroslužeb
  • Klikněte na tlačítko Vytvořit funkci

  • Na nové stránce funkce AWS Lambda vyberte pro položku Typ zadání kódu možnost Upravit vložený kód a pro položku Obslužná rutina zachovejte nastavení index.handler.
  • Přidejte logiku pro registraci webhooku služby Acrobat Sign

    Před úspěšnou registrací webhooku služba Acrobat Sign ověří, zda adresa URL webhooku, která je uvedena v žádosti o registraci, skutečně zamýšlí přijímat oznámení, nebo nikoli. Za tímto účelem služba Acrobat Sign při obdržení nového požadavku na 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 s vlastní hlavičkou HTTP X-AdobeSign-ClientId. Hodnota v tomto záhlaví je nastavena na ID klienta aplikace, která požaduje vytvoření/registraci webhooku. K dosažení úspěšné registrace webhooku musí adresa URL webhooku odpovědět na požadavek 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ů. Všimněte si také, že stejné chování pro ID klienta je očekáváno, když adresa URL webhooku přijme oznámení POST.

    Postupujte podle jednoho z těchto dvou případů:

    Případ 1: Předání ID klienta v X-AdobeSign-ClientId jako hlavičce odpovědi

    •  Předejte X-AdobeSign-ClientId v hlavičce odpovědi. Jedná se o stejnou hlavičku, která byla předána v požadavku, a musí být vrácena v odpovědi.

      Fragment kódu
      V souboru index.js nahraďte automaticky generovaný fragment kódu následujícím kódem:

Ukázka kódu JS uzlu pro načtení ID klienta, jeho ověření a následné vrácení v hlavičce odpovědi

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

  // Fetch client id

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

 

  //Validate it

  if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! illegitimate call");

  }

}

 

Případ 2: Předání ID klienta v těle odpovědi pomocí klíče xAdobeSignClientId

Předejte ID klienta v těle odpovědi JSON pomocí klíče xAdobeSignClientId, jehož hodnota se shoduje s ID klienta, které bylo zasláno v hlavičce požadavku.

 

Fragment kódu

Nahraďte kód souboru Index.js následujícím kódem:

Ukázka kódu JS uzlu pro načtení ID klienta, jeho ověření a následné vrácení v hlavičce odpovědi

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

 // Fetch client id

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

  

 //Validate it

 if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Opps!! illegitimate call");

  }

}

  • Uložte funkci. Funkce Lambda je vytvořena a je téměř připravena k použití ve webhooku v reálném čase.

 

Konfigurace brány AWS API

Pokud má být tato funkce Lambda veřejně přístupná prostřednictvím metody HTTP, je nutné nakonfigurovat bránu AWS API pomocí naší funkce (vytvořené výše) jako backend pro rozhraní API.

V konzole pro správu AWS vyberte ze seznamu služeb AWS možnost Brána API a poté klikněte na tlačítko Vytvořit rozhraní API

  • Na stránce Vytvořit nové rozhraní API vyberte možnost Nové rozhraní API a do pole Název rozhraní API zadejte text webhooky.
  • Klikněte na tlačítko Vytvořit rozhraní API
  • Vyberte rozevírací seznam Akce a zvolte možnost Vytvořit zdroj
  • Zaškrtněte políčko Konfigurovat jako zdroj proxy, do pole Název zdroje zadejte text ověřit a do pole Cesta ke zdroji zadejte text {proxy+}
  • Zrušte zaškrtnutí políčka Aktivovat CORS brány API a klikněte na tlačítko Vytvořit zdroj
  • V poli Typ integrace ponechte vybranou možnost Funkce Lambda Proxy a v rozevíracím seznamu Oblast Lambda vyberte oblast, ve které jste vytvořili funkci Lambda (pravděpodobně se jedná o stejnou oblast, ve které vytváříte bránu API).
  • Do pole Funkce Lambda zadejte text ověřit a klikněte na tlačítko Uložit
  • V automaticky otevřeném okně Přidat oprávnění k funkci Lambda vyberte tlačítko OK

Pokud všechny výše uvedené kroky proběhnou úspěšně, zobrazí se podobná obrazovka, jako je tato:

Nasazení rozhraní API

Dalším krokem je nasazení tohoto rozhraní API, aby bylo připraveno k použití.

  • V rozevírací nabídce Akce vyberte možnost Nasadit rozhraní API
  • V poli Fáze nasazení vyberte možnost [Nová fáze] a do pole Název fáze zadejte text prod (nebo jakýkoli jiný text, kterým chcete tuto fázi identifikovat)
  • Klikněte na tlačítko Nasadit

Rozhraní API je nyní připraveno k použití a adresu URL pro vyvolání najdete v modrém poli, jak je zobrazeno níže:

Poznamenejte si tuto adresu URL, protože ji budete muset zadat jako adresu URL webhooku v reálném čase.

 

Připraveno k použití

Je to hotovo. Použijte výše uvedenou adresu URL doplněnou o řetězec „/{nodeJSfunctionName}“ jako adresu URL webhooku v rozhraní API POST /webhooky.  Po ověření chování je adresa URL webhooku funkční podle
standardů služby Acrobat Sign. Dále můžete aktualizovat nebo přidat vlastní logiku podle svých požadavků.


Možnosti konfigurace

Konfigurace webhooku vyžaduje definování pěti prvků, kterými jsou:

  • Název – Je doporučeno použít intuitivní název, který ostatní správci snadno pochopí
  • Rozsah – Určuje šířku sítě pro použití webhooku. V rozhraní je k dispozici Účet a Skupina
    • Rozhraní API podporuje rozsahy Účet, Skupina, Uživatel a Zdroj
    • K jednomu webhooku lze nastavit pouze jeden rozsah
  • Adresa URL – Cílová adresa URL, na kterou služba Acrobat Sign přesunula datovou část JSON
  • Události – Aktivační událost, která způsobí, že služba Acrobat Sign sestaví JSON a odešle jej na adresu URL
    • Každá událost vytváří jinou datovou část, která souvisí s aktivační událostí
    • Do jednoho webhooku lze zahrnout více událostí
  • Parametry oznámení – Parametry oznámení identifikují jednotlivé sekce datové části JSON události, a umožňují tak vybrat pouze ty sekce události, které jsou pro tento webhook důležité (a tím omezit zbytečná data v adrese URL).

 

Jakmile bude webhook plně definován, klikněte na tlačítko Uložit a nový webhook začne okamžitě reagovat na aktivační události. 

Poznámka:

Nakonfigurujte adresu URL webhooku tak, aby reagovala na požadavky na ověření webhooku a na oznámení webhooku podle výše vysvětleného ověřovacího protokolu. ID klienta (ID aplikace), které bude odesíláno webhookům vytvořeným z webové aplikace Acrobat Sign, bude – UB7E5BXCXY.

Konfigurace webhooku


Rozsahy ověřování

  • Účet: Všechny odebírané události, které se vyskytnou na účtu, aktivují odeslání 
    • Správci účtu mají oprávnění k zobrazení všech webhooků definovaných pro účet / všechny skupiny.
  • Skupina: Všechny odebírané události, které se vyskytnou v dané skupině, aktivují odeslání. Webhooky s rozsahem vymezeným na skupinu existují pouze v jedné skupině.
    • Správci skupiny uvidí pouze webhooky, které jsou určeny pro jejich skupinu. Neuvidí webhooky na úrovni účtu ani webhooky vázané na jiné skupiny.
    • Pro účty, které mají aktivovánu funkci Uživatelé ve více skupinách, se zobrazí možnost k nastavení skupiny, na kterou se má rozsah vztahovat.
  • Uživatelský účet: Všechny odebírané události pro uživatelský účet aktivují odeslání. Webhooky na úrovni uživatele lze vytvářet pouze přes rozhraní API.
  • Webhook na úrovni zdroje: Bude vytvořen pro konkrétní zdroj. Události specifické pro tento zdroj budou odesílány na adresu URL webhooku. Webhooky na úrovni zdroje lze vytvářet pouze přes rozhraní API.


Adresa URL

Adresa URL webhooku je server, jenž naslouchá příchozím oznamovacím zprávám HTTPS POST, které jsou aktivovány při výskytu událostí.

Tuto adresu URL potřebujete k přihlášení webhooku k odběru událostí.

  • Klient musí obsahovat adresu HTTPS URL, na kterou může služba Acrobat Sign zasílat zprávy POST. Tato adresa URL musí být dostupná na veřejném internetu.  
    • Například URI 127.0.0.1 a localhost nebudou fungovat.
    • Koncový bod adresy URL musí naslouchat na portu 443.
  • Ujistěte se, že webhook podporuje požadavky POST pro příchozí oznámení událostí a požadavky GET pro žádost o ověření.
  • Adresa URL nesmí být blokována bránou firewall.


Události

Níže jsou uvedeny události, které mohou aktivovat odeslání na adresu URL webhooku, seskupené podle objektu.

Každá událost má šablonu datové části JSON, kterou lze doručit. (Kliknutím na název události zobrazíte detaily příslušné datové části):

  • Hromadné odeslání (dříve Mega Sign) – události Hromadné odeslání se týkají pouze vytvoření nadřazeného objektu Hromadné odeslání. Výsledné podřízené dohody jsou sledovány jako události dohody.  
    • Všechny události hromadného odeslání – zahrnuje všechny události Hromadné odeslání. Pokud budou v budoucnu definovány další události, budou automaticky zahrnuty do tohoto nastavení.  Datová část JSON je založena na jednotlivé události, která je aktivována
    • Hromadné odeslání vytvořeno – při vytvoření hromadného odeslání
    • Hromadné odeslání sdíleno – při sdílení hromadného odeslání
    • Hromadné odeslání odvoláno – při odvolání hromadného odeslání
  • Webový formulář (dříve Widgety) – události webového formuláře se týkají pouze vytvoření šablony webového formuláře. Výsledné podřízené dohody jsou sledovány jako události dohody.
    • Všechny události widgetu – zahrnuje všechny události webového formuláře. Pokud budou v budoucnu definovány další události, budou automaticky zahrnuty do tohoto nastavení.  Datová část JSON je založena na jednotlivé události, která je aktivována
    • Widget vytvořen – při vytvoření webového formuláře
    • Widget povolen – při povolení webového formuláře
    • Widget zakázán – při zakázání webového formuláře
    • Widget upraven – při úpravě webového formuláře
    • Widget sdílen – při sdílení webového formuláře
    • Vytvoření widgetu selhalo – při automatickém zrušení webového formuláře z důvodu problému s převodem


Parametry upozornění

Parametry upozornění umožňují přizpůsobit datovou část JSON pouze určitým prvkům události.

Například v případě události Účastník dohody nahrazen můžete chtít pouze informace o dohodě a informace o účastníkovi, zatímco informace o dokumentu můžete chtít vynechat, aby se snížil celkový objem dat pro adresu URL webhooku

 

  • Dohoda
    • Informace o dohodě – podrobné informace o dohodě založené na stavu dohody v době aktivační události
    • Informace o dokumentu dohody – zahrnuje veškeré informace o dokumentu generované v důsledku události
    • Informace o účastníkovi dohody – zahrnuje veškeré informace o účastníkovi v důsledku události
    • Podepsaný dokument dohody – poskytuje podepsaný dokument PDF. 
      • Platí pro události Pracovní postup dohody dokončen a Všechny události dohody
  • Hromadné odeslání
    • Informace o hromadném odeslání – podrobné informace o objektu Hromadné odeslání, který událost aktivoval
  • Webový formulář
    • Informace o widgetu – podrobné informace o webovém formuláři, který událost aktivoval
    • Informace o dokumentu widgetu – informace o dokumentu spojené se šablonou webového formuláře
    • Informace o účastníkovi widgetu – informace o definovaných účastnících v šabloně webového formuláře


Ověřování obousměrným protokolem SSL

Obousměrný protokol SSL, často označovaný jako protokol SSL nebo oboustranný protokol TLS na straně klienta, je režim protokolu SSL, v němž server i klient (webový prohlížeč) předkládají certifikáty pro svou identifikaci.

Správci účtu mohou konfigurovat certifikát na straně klienta na stránce Nastavení zabezpečení.

Služba Acrobat Sign ověřuje certifikáty SSL při doručování datových částí na adresu URL webhooku. Webhooky, které neuspějí při ověřování certifikátu SSL, nedoručí úspěšně datovou část JSON. 

K ověření klienta (Acrobat Sign) a naslouchající služby použijte obousměrný protokol SSL, abyste zajistili, že přístup k adrese URL webhooku získá pouze služba Acrobat Sign. 

Pokud byl webhook vytvořen partnerskou aplikací, použije webhook k identifikaci při zpětných voláních webhooku klientský certifikát (je-li k dispozici) z účtu partnerské aplikace.

Níže jsou nejčastější otázky týkající procesu ověřování webového serveru a ověřování certifikace klienta.

Ověřování webového serveru

Během registrace webhooku služba Acrobat Sign ověřuje adresu URL serveru webhooku.

Zákazníci nebudou moci webhook zaregistrovat, pokud nelze ze služby Acrobat Sign dokončit zpětné volání adresy URL webhooku.

Ne.

Zpětné volání adresy URL webhooku může být pouze protokol HTTPS na portu 443.

Služba Acrobat Sign blokuje odchozí datové přenosy HTTPS do všech ostatních portů.

Dobrý způsob, jak ověřit certifikát serveru, je použít nástroj DigiCert® SSL Installation Diagnostics Tool.

Stačí zadat pouze název hostitele, např.: www.digicert.com

K běžným problémům patří:

  • Problém: Použití nedůvěryhodné certifikační autority nebo certifikát s vlastním podpisem

Náprava: Pro server zpětného volání webhooku použijte certifikát SSL vydaný veřejnou certifikační autoritou.

Nedůvěryhodná certifikační autorita

  • Problém: Server neodesílá zprostředkující certifikát

Náprava: Nainstalujte zprostředkující certifikáty na server zpětného volání webhooku.

Viz webová stránka https://www.digicert.com/kb/ssl-certificate-installation.htm, kde najdete podrobné informace.

Chybějící zprostředkující certifikáty

Ověřování klientského certifikátu

Aby bylo možné nastavit obousměrný protokol SSL pro webhook, vyžadujeme aby správce nahrál soubor .p12 (nebo .pfx), který obsahuje pouze soukromý klíč. Soubor je bezpečně uložen v účtu zákazníka a správce má nad ním plnou kontrolu a může jej kdykoli odebrat.

V konfiguraci obousměrného webhooku je služba Acrobat Sign volající/klient a potřebuje soukromý klíč jako důkaz, že volání pochází ze služby Acrobat Sign jménem účtu zákazníka.

  1. Ověření, že je povolený obousměrný protokol SSL

    Na serveru zpětného volání webhooku musí být povolený obousměrný protokol SSL.

    Pomocí libovolného webového prohlížeče se připojte k adrese URL zpětného volání webhooku. Měla by se zobrazit zpráva:

    400 Špatný požadavek
Nebyl odeslán požadovaný certifikát SSL

    To znamená, že server očekává od klienta zaslání klientských certifikátů (tj. na serveru je povolený obousměrný protokol SSL).

    Pokud se vám výše uvedená zpráva nezobrazí, pak obousměrný protokol SSL povolený není.

    Poznámka:

    K vyžádání adresy URL zpětného volání webhooku můžete použít aplikaci Postman a provést požadavek POST. Výsledek by měl být podobný.

  2. Místní ověření klientského certifikátu

    Ověřovací údaje klienta může tvořit buď certifikát s vlastním podpisem, nebo certifikát vydaný certifikační autoritou. Musí však splňovat minimálně tyto přípony X.509 v3:

    přípona X.509 v3

    Hodnota

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    Klientský certifikát musí být soubor PKCS12 s příponou .p12 nebo .pfx, a musí obsahovat jak klientský certifikát (aby mohl server ověřit identitu klienta), tak klientův soukromý klíč (aby mohl klient digitálně podepisovat zprávy pro server pro účely ověření během procesu SSL handshake). 

    Použijte příkaz openssl k ověření souboru p12 (pfx):

    openssl pkcs12 -info -in outfile.p12

    Mělo by být vyžádáno heslo pro soukromý klíč. Výstup by měl obsahovat oba certifikáty i šifrovaný soukromý klíč, jako je například:

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

    Certifikáty by měly obsahovat přinejmenším certifikát koncového subjektu a zprostředkující certifikáty. V ideálním případě budou zahrnovat také certifikát kořenové certifikační autority.  

    Ujistěte se, že je soubor .p12 nebo .pfx chráněn heslem.

  3. Vytvořte klientský certifikát s vlastním podpisem (volitelné)

    Klientské certifikáty mohou být vydané certifikační autoritou nebo certifikáty s vlastním podpisem, podle vašich potřeb.

    Chcete-li generovat klientský certifikát s vlastním podpisem, použijte následující příkaz openssl :

    openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

    Pozor:

    Výsledné soubory uchovávejte v tajnosti, protože se jedná o vaše certifikáty certifikační autority (CA) s vlastním podpisem.

    V dalším kroku vygenerujte klientský soubor .p12:

    1. Vygenerujte soukromý klíč pro klienta SSL:

      openssl genrsa -out client.key 2048

    2. Pomocí klientova soukromého klíče vygenerujte žádost o certifikát:

      openssl req -new -key client.key -out client.req

    3. Vydejte klientský certifikát s použitím žádosti o certifikát a certifikátu/klíče CA:

      openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer

    4. Převeďte klientský certifikát a soukromý klíč do formátu pkcs#12 pro použití v prohlížečích:

      openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12

    5. Odeberte klientův soukromý klíč, klientský certifikát a klientovy soubory žádostí, protože soubor pkcs12 obsahuje vše, co potřebujete.

      rm client.key client.cer client.req

  4. Ověřte klientský certifikát u vzdáleného serveru

    • Pomocí aplikace Postman načtěte klientský soubor PFX v nabídce Nastavení > Certifikáty.
    • Vyberte možnost Přidat certifikát a přidejte klientský certifikát.
    Nastavení aplikace Postman

    • Nakonfigurujte záhlaví HTTP pro x-adobesign-clientid:
    Nakonfigurujte záhlaví

    Jakmile je konfigurace hotova, odešlete požadavek POST na adresu URL zpětného volání webhooku.

    Měli byste dostat odpověď 200.

  5. Proč služba Acrobat Sign odmítá můj soubor PFX i po ověření pomocí aplikace Postman?

    Pokud jste dodrželi výše uvedený proces ověření souboru pfx a služba Acrobat Sign přesto odmítá soubor pfx, byl pravděpodobně generován pomocí nástroje Microsoft, který může vytvořit nestandardní soubor PKCS12.

    V takovém případě použijte níže uvedené příkazy openssl k extrahování certifikátů a soukromého klíče ze souboru pfx a poté vygenerujte správně naformátovaný soubor PKCS12:

    // Extrahujte certifikáty a soukromý klíč ze souboru pfx
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts

// Vytvořte nový soubor PKCS12
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx


Postup povolení nebo zakázání

Přístup k funkci Webhooky je ve výchozím nastavení povolen pro účty s podnikovým plánem.

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: Účet > Webhooky


Aktivace webhooku

První webhook je vytvořen ve stavu Aktivní.

Na stránce Webhooky ve službě Acrobat Sign se při výchozím nastavení zobrazí aktivní webhooky.

Aktivace neaktivního webhooku:

  • Klikněte na ikonu Možnosti (tři vodorovné čáry) na pravé straně řádku záhlaví seznamu webhooků a vyberte možnost Zobrazit všechny webhooky

 

  • Vyberte neaktivní webhook jedním kliknutím
    • Tím zobrazíte těsně pod řádkem záhlaví možnosti pro webhook
  • Klikněte na tlačítko Aktivovat

Aktivní webhook začne odesílat data na cílovou adresu URL, jakmile dojde k aktivaci další události.


Deaktivace webhooku

Deaktivace webhooku vyžaduje, abyste provedli pouze následující kroky:

  • Přejděte na stránku Webhooky
  • Kliknutím vyberte webhook, který chcete deaktivovat
  • Z položek nabídky pod řádkem záhlaví vyberte položku Deaktivovat
    • Po deaktivaci se pro webhook zobrazí stav Neaktivní


Zobrazení nebo úprava webhooku

Webhooky lze kdykoli upravit a uložit, přičemž po uložení nové konfigurace se změny projeví okamžitě.

Upravit lze pouze položky Události a Parametry oznámení.

Pokud je potřebné změnit nastavení položek Název, Rozsah a Adresa URL, bude nutné vytvořit nový webhook.

Úprava parametrů webhooku:

  • Přejděte na stránku Webhooky
  • Kliknutím vyberte webhook, který chcete upravit
  • Klikněte na možnost Zobrazit/Upravit pod řádkem záhlaví

 

  • Proveďte všechny potřebné změny a klikněte na tlačítko Uložit


Odstranění webhooku

Webhook lze kdykoli odstranit.

Odstraněním webhooku dojde k jeho zničení v systému, takže odstraněný webhook nelze obnovit.

Webhooky není nutné nejprve deaktivovat.

Odstranění webhooku:

  • Přejděte na stránku Webhooky
  • Kliknutím vyberte webhook, který chcete odstranit
  • Klikněte na možnost Odstranit pod řádkem záhlaví
  • Zobrazí se dotaz, zda chcete webhook skutečně odstranit. klikněte na tlačítko OK


Osvědčené postupy

  • 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 deset 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. 

Pokud například potřebujete zpracovat a následně uložit podepsané dokumenty. Chcete-li mít jistotu, že vždy dokážete odpovědět do deseti sekund, měli byste práci vždy provádět v samostatném vlákně nebo asynchronně pomocí fronty.

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

1. Jaká data chcete vracet v datové části? 

2. Kdo bude přistupovat k těmto informacím? 

3. 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 poskytují oznámení, která se vztahují na všechny účastníky dohody, pokud je webhook nakonfigurován pro daného uživatele, jeho skupinu nebo účet.

Události dohody jsou zpracovávány tak, že pokud je pro příslušného účastníka dané události nakonfigurován webhook, je oznámení odesláno na adresu URL tohoto webhooku. Jinými slovy, webhooky jsou aktivovány pro události ve všech platných dohodách, včetně těch, které nejsou součástí skupiny nebo účtu, ve kterém je webhook nakonfigurován.

Oznámení jsou doručována pouze pro ty události, do kterých je účastník zapojen. Například odesílatel dohody obdrží téměř každé oznámení, zatímco příjemci budou dostávat oznámení pouze od začátku své účasti na dohodě a pouze pro události, kterých se účastní.

Oznámení webhooku se řídí současným modelem ověřování a viditelnosti samotné služby Acrobat Sign, takže uživatelé budou mít přístup k dohodě až po zahájení své účasti na této dohodě.

Odesílatel odešle dohodu k podpisu třem podepisujícím.

  • Pro účet odesílatelů je nakonfigurován webhook X na úrovni účtu.
  • Podepisující 1 je členem stejného účtu jako odesílatel, ale v jiné skupině, pro kterou je nakonfigurován webhook Y.
  • Podepisující 2 je členem jiného účtu, ve kterém je nakonfigurován webhook Z pro podepisujícího 2 na úrovni účtu.
  • Podepisující 3 je členem stejného účtu jako odesílatel.

Odesílatel odešle dohodu: webhook X aktivuje události „Dohoda vytvořena“ a „Dohoda odeslána“, zatímco Webhook Y aktivuje událost „Dohoda odeslána“.

Podepisující 1 podepíše: webhook X aktivuje události „Účastník dohody dokončil“ a „Dohoda odeslána“, webhook Y aktivuje událost „Účastník dohody dokončil“ a webhook Z aktivuje událost „Dohoda odeslána“.

Podepisující 2 podepíše: webhook X aktivuje události „Účastník dohody dokončil“ a „Dohoda odeslána“, zatímco webhook Z odešle oznámení pro „Účastník dohody dokončil“.

Podepisující 3 podepíše: webhook X aktivuje události „Účastník dohody dokončil“ a „Pracovní postup dohody dokončen“, webhook Y aktivuje událost „Pracovní postup dohody dokončen“ a webhook Z aktivuje událost „Pracovní postup dohody dokončen“.


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.

Logo Adobe

Přihlaste se ke svému účtu.

Rychlé odkazy

Zobrazit všechny vaše plány Správa plánů

Legal Notices    |    Online Privacy Policy