Przykładowy kod JavaScript do pobrania identyfikatora klienta, sprawdzenia jego poprawności, a następnie zwrócenia go w nagłówku odpowiedzi
Ostatnia aktualizacja
10 sty 2024
|
Dotyczy również Adobe Acrobat Sign
- Integracje z usługą Adobe Acrobat Sign
- Nowości
- Wersje produktów i cykl eksploatacji
- Acrobat Sign dla Salesforce
- Instalacja pakietu
- Konfiguracja pakietu
- Podręcznik użytkownika
- Włączanie uwierzytelniania cyfrowego
- Podręcznik dla programistów
- Instrukcja wprowadzania ustawień zaawansowanych
- Instrukcja mapowania pól i szablonów
- Podręcznik użytkownika aplikacji mobilnej
- Przewodnik automatyzacji obiegów
- Przewodnik narzędzia Document Builder
- Konfigurowanie dużych dokumentów
- Instrukcja aktualizacji
- Informacje o wydaniu
- Często zadawane pytania
- Przewodnik rozwiązywania problemów
- Dodatkowe artykuły
- Acrobat Sign dla Microsoft
- Acrobat Sign dla Microsoft 365
- Acrobat Sign dla Outlook
- Acrobat Sign dla programu Word/PowerPoint
- Acrobat Sign dla Teams
- Acrobat Sign dla Microsoft PowerApps i Power Automate
- Łącznik Acrobat Sign dla Microsoft Search
- Acrobat Sign dla Microsoft Dynamics
- Acrobat Sign dla Microsoft SharePoint
- Omówienie
- SharePoint On-Prem: Instrukcja instalacji
- SharePoint On-Prem: Instrukcja mapowania szablonu
- SharePoint On-Prem: Podręcznik użytkownika
- SharePoint On-Prem: Informacje o wydaniu
- SharePoint Online: Instrukcja instalacji
- SharePoint Online: Instrukcja mapowania szablonu
- SharePoint Online: Podręcznik użytkownika
- SharePoint Online: Instrukcja mapowania formularzy internetowych
- SharePoint Online: Informacje o wydaniu
- Acrobat Sign dla Microsoft 365
- Acrobat Sign dla ServiceNow
- Acrobat Sign dla HR ServiceNow
- Acrobat Sign dla SAP SuccessFactors
- Acrobat Sign dla oprogramowania Workday
- Acrobat Sign dla NetSuite
- Adobe Acrobat Sign dla SugarCRM
- Acrobat Sign dla VeevaVault
- Acrobat Sign dla Coupa BSM Suite
- Acrobat Sign dla Zapier
- Acrobat Sign — dokumentacja programisty
Omówienie
Element webhook to zdefiniowane przez użytkownika żądanie HTTPS, które jest wyzwalane, gdy w witrynie źródłowej wystąpi subskrybowane zdarzenie (w tym przypadku Adobe Acrobat Sign).
Efektywnie zatem element webhook to tylko usługa REST, która przyjmuje dane lub strumień danych.
Elementy webhook służą do komunikacji między usługami w model PUSH.
Gdy wystąpi subskrybowane zdarzenie, program Acrobat Sign konstruuje wiadomość HTTPS POST z treścią JSON i dostarcza ją pod określony adres URL.
Elementy webhook oferują wiele korzyści w stosunku do poprzedniej metody wywołania zwrotnego, a niektóre z nich to:
- Administratorzy mogą włączać elementy webhook bez konieczności angażowania pomocy technicznej programu Acrobat Sign w celu wyszczególnienia adresu URL wywołania zwrotnego.
- Elementy webhook są lepsze pod względem „świeżości” danych, wydajności komunikacji i bezpieczeństwa. Nie jest wymagane sondowanie.
- Elementy webhook umożliwiają łatwe tworzenie różnych poziomów zakresu (Konto/Grupa/Użytkownik/Zasoby).
- Elementy webhook są nowocześniejszym rozwiązaniem API, umożliwiającym prostszą konfigurację nowoczesnych aplikacji.
- Możliwość skonfigurowania wielu elementów webhook dla każdego zakresu (konto/grupa/użytkownik/zasób), gdzie wywołania zwrotne musiały być unikalne.
- Elementy webhook pozwalają na wybór danych, które mają być zwrócone, podczas gdy wywołania zwrotne są rozwiązaniem typu „wszystko albo nic”.
- Metadane przenoszone przez elementy webhook można skonfigurować (Podstawowe lub Szczegółowe).
- Elementy webhook znacznie łatwiej jest tworzyć, edytować i wyłączać w razie potrzeby, ponieważ interfejs użytkownika znajduje się całkowicie pod kontrolą administratora.
Uwaga:
Ten dokument dotyczy przede wszystkim interfejsu użytkownika elementów webhook w aplikacji internetowej Acrobat Sign (poprzednio Adobe Sign).
Programiści, którzy poszukują szczegółowych informacji na temat interfejsu API, mogą znaleźć więcej informacji tutaj:
Korzystanie
Administratorzy będą musieli najpierw utworzyć usługę elementów webhook, gotową do przyjmowania przychodzących komunikatów od programu Acrobat Sign. Istnieje wiele opcji w tym zakresie, a jeśli tylko usługa może przyjmować żądania POST i GET, element webhook będzie działał poprawnie.
Po wprowadzeniu usługi administrator programu Acrobat Sign może utworzyć nowy element webhook za pomocą interfejsu Webhook w menu Konto na stronie programu Acrobat Sign.
Administratorzy mogą skonfigurować element webhook tak, aby wyzwalał się w przypadku zdarzeń typu Umowa, Formularz internetowy (widżet) lub Wyślij zbiorczo (MegaSign). Zasób szablonu biblioteki (dokument biblioteki) można również skonfigurować za pośrednictwem interfejsu API.
Zakres elementu webhook może obejmować całe konto lub poszczególne grupy za pośrednictwem interfejsu administratora. Interfejs API zapewnia większą szczegółowość poprzez wybór zakresów USER lub RESOURCE.
Rodzaj danych przesyłanych do adresu URL jest konfigurowalny i może obejmować takie elementy, jak informacje o umowie, informacje o uczestniku, informacje o dokumencie itd.
Po skonfigurowaniu i zapisaniu elementu webhook program Acrobat Sign będzie przesyłał nowy obiekt JSON pod zdefiniowany adres URL za każdym razem, gdy subskrybowane zdarzenie zostanie wyzwolone. Nie jest wymagana bieżąca manipulacja elementem webhook, chyba że użytkownik chce zmienić kryteria wyzwalania zdarzeń lub zawartość pliku JSON.
Weryfikacja intencji adresu URL elementu webhook
Przed pomyślnym zarejestrowaniem elementu webhook program Acrobat Sign sprawdza, czy adres URL elementu webhook podany w żądaniu rejestracji jest przeznaczony do otrzymywania powiadomień, czy też nie. W tym celu po otrzymaniu przez aplikację Acrobat Sign nowego żądania rejestracji elementu webhook, najpierw wysyła ona żądanie weryfikacji na adres URL elementu webhook. To żądanie weryfikacji jest żądaniem HTTPS GET wysyłanym do adresu URL elementu webhook. To żądanie zawiera niestandardowy nagłówek HTTP X-AdobeSign-ClientId. Wartość w tym nagłówku jest ustawiana na identyfikator klienta (identyfikator aplikacji) aplikacji API, która żąda utworzenia/zarejestrowania elementu webhook. Aby pomyślnie zarejestrować element webhook, adres URL elementu webhook musi odpowiedzieć na to żądanie weryfikacji za pomocą kodu odpowiedzi 2XX ORAZ dodatkowo MUSI zwrócić tę samą wartość identyfikatora klienta za pomocą jednego z następujących dwóch sposobów:
- Albo w nagłówku odpowiedzi X-AdobeSign-ClientId. Jest to ten sam nagłówek, który został przekazany w żądaniu i jest ponownie przywoływany w odpowiedzi.
- Albo w treści odpowiedzi JSON z kluczem xAdobeSignClientId i jego wartością jest ten sam identyfikator klienta, który został wysłany w żądaniu.
Element webhook zostanie pomyślnie zarejestrowany tylko po uzyskaniu odpowiedzi pozytywnej (kod odpowiedzi 2XX) i sprawdzeniu poprawności identyfikatora klienta w nagłówku lub treści odpowiedzi. Celem tego żądania weryfikacji jest wykazanie, że adres URL elementu webhook chce otrzymywać powiadomienia pod tym adresem. Jeśli przypadkowo wprowadzono nieprawidłowy adres URL, adres ten nie odpowie poprawnie na żądanie weryfikacji zamiarów, a program Acrobat Sign nie wyśle żadnych powiadomień na ten adres URL. Ponadto adres URL elementu webhook może również potwierdzić, że będzie otrzymywać powiadomienia tylko za pośrednictwem elementów webhook zarejestrowanych przez konkretną aplikację. Można to zrobić, sprawdzając poprawność identyfikatora klienta aplikacji przekazanego w nagłówku X-AdobeSign-ClientId. Jeśli adres URL elementu webhook nie rozpoznaje tego identyfikatora klienta, NIE MOŻE odpowiedzieć kodem odpowiedzi „powodzenie”, a program Acrobat Sign zadba o to, aby adres URL nie został zarejestrowany jako element webhook.
Weryfikacja wywołania adresu URL elementu webhook będzie przeprowadzana w następujących scenariuszach:
- Rejestracja elementu webhook: jeśli ta weryfikacja adresu URL elementu webhook nie powiedzie się, element webhook nie zostanie utworzony.
- Aktualizacja elementu webhook: NIEAKTYWNY do AKTYWNY: jeśli ta weryfikacja wywołania adresu URL elementu webhook nie powiedzie się, stan elementu webhook nie zostanie zmieniony na AKTYWNY.
Jak odpowiedzieć na powiadomienie elementu webhook
Program Acrobat Sign przeprowadza niejawną weryfikację intencji w każdym żądaniu powiadomienia elementu webhook wysyłanym do adresu URL elementu webhook. Dlatego każde żądanie HTTPS powiadomienia elementu webhook zawiera również niestandardowy nagłówek HTTP o nazwie X-AdobeSign-ClientId. Wartością tego nagłówka jest identyfikator klienta (ID aplikacji) aplikacji, która utworzyła element webhook. Powiadomienie elementu webhook zostanie uznane za pomyślnie dostarczone, jeśli, i tylko jeśli, zostanie zwrócona odpowiedź powodzenia (kod odpowiedzi 2XX) i identyfikator klienta zostanie wysłany w nagłówku HTTP (X-AdobeSign-ClientId) lub w treści odpowiedzi JSON z kluczem jako xAdobeSignClientId i wartością jako ten sam identyfikator klienta, w przeciwnym razie będziemy ponawiać próby dostarczenia powiadomienia na adres URL elementu webhook aż do wyczerpania limitu prób.
Jak wspomniano powyżej, nagłówek „X-AdobeSign-ClientId” , który jest dołączany do każdego żądania powiadomienia od Sign, wartość tego nagłówka (identyfikator klienta) powinna być powtórzona w odpowiedzi na jeden z dwóch sposobów:
1. Nagłówek HTTP X-AdobeSign-ClientId i wartość jako identyfikator tego klienta
|
|
|---|
|
// 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 } |
|
Przykładowy kod PHP do pobrania identyfikatora klienta, sprawdzenia jego poprawności, a następnie zwrócenia go w nagłówku odpowiedzi |
|---|
|
<?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. Treść odpowiedzi JSON z kluczem jako xAdobeSignClientId i wartością jako tym samym identyfikatorem klienta
|
Przykładowy kod Javascript do pobrania identyfikatora klienta, sprawdzenia jego poprawności i zwrócenia go w treści odpowiedzi |
|---|
|
// 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; } |
|
Przykładowy kod PHP do pobrania identyfikatora klienta, sprawdzenia jego poprawności i zwrócenia go w treści odpowiedzi |
|---|
|
<?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 } ?> |
|
Przykładowa treść odpowiedzi w formacie JSON |
|---|
|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
Wymagania wstępne
Potrzebne będą:
- Konto Microsoft z licencją na tworzenie aplikacji Azure Functions
- Istniejąca aplikacja Azure Function, można ją utworzyć za pomocą strony https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function
- Podstawowa znajomość języka Javascript, umożliwiająca zrozumienie i napisanie kodu w dowolnie wybranym języku
Kroki tworzenia wyzwalacza Azure Functions, który posłuży jako element webhook Acrobat Sign
Aby utworzyć funkcję wyzwalacza HTTP Javascript:
1. Zaloguj się za pomocą konta Microsoft https://portal.azure.com/
2. Otwórz aplikację Azure Function wyświetlaną na karcie Function Apps.
Spowoduje to otwarcie listy aplikacji Azure Function:
3. Wybierz aplikację, w której chcesz utworzyć nową funkcję
4. Kliknij przycisk Utwórz (+), aby utworzyć nową funkcję Azure
5. Wybierz opcję Webhook + API jako scenariusz oraz JavaScript jako język
6. Kliknij przycisk Utwórz tę funkcję
Tworzona jest nowa funkcja, która może obsługiwać przychodzące żądanie API.
Dodawanie logiki, aby zarejestrować element webhook Acrobat Sign
Przed pomyślnym zarejestrowaniem elementu webhook program Acrobat Sign sprawdza, czy adres URL elementu webhook podany w żądaniu rejestracji jest rzeczywiście przeznaczony do otrzymywania powiadomień, czy też nie. W tym celu, gdy program Acrobat Sign otrzymuje nowe żądanie rejestracji elementu webhook, najpierw kieruje żądanie weryfikacji na adres URL elementu webhook. To żądanie weryfikacji jest żądaniem HTTPS GET wysyłanym do adresu URL elementu webhook z niestandardowym nagłówkiem HTTP X-AdobeSign-ClientId. Wartość w tym nagłówku jest ustawiana na identyfikator klienta aplikacji, która żąda utworzenia/zarejestrowania elementu webhook. Aby pomyślnie zarejestrować element webhook, adres URL elementu webhook musi odpowiedzieć na to żądanie weryfikacji za pomocą kodu odpowiedzi 2XX ORAZ dodatkowo musi zwrócić tę samą wartość identyfikatora klienta za pomocą jednego z następujących dwóch.
Istnieją dwie opcje, zgodnie z którymi można postąpić:
Opcja 1: Przekaż identyfikator klienta w X-AdobeSign-ClientId jako nagłówek odpowiedzi
Przekaż X-AdobeSign-ClientId w nagłówku odpowiedzi. Jest to ten sam nagłówek, który został przekazany w żądaniu i musi być ponownie przywoływany w odpowiedzi.
Zastąp plik Index.js następująca treścią:
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();
};
Przetestuj zachowanie, symulując żądanie:
1. Kliknij przycisk Test w skrajnie prawym rogu
2. Zasymuluj żądanie pozorne
Co prawda nagłówki odpowiedzi nie są pokazane powyżej, ale można je zaobserwować, symulując je za pomocą usługi Postman/DHC lub innej.
Opcja 2: Przekaż identyfikator klienta w treści odpowiedzi za pomocą klucza xAdobeSignClientId
W treści odpowiedzi JSON z kluczem xAdobeSignClientId i jego wartością jest ten sam identyfikator klienta, który został wysłany w nagłówku żądania.
Zastąp plik Index.js następująca treścią:
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();
};
Przetestuj zachowanie, symulując żądanie
1. Kliknij przycisk Test w skrajnie prawym rogu
2. Zasymuluj żądanie pozorne
Należy również pamiętać, że takie samo zachowanie dla clientID jest oczekiwane, gdy adres URL elementu webhook otrzymuje powiadomienia POST.
Gotowe do użycia
Po zweryfikowaniu zachowania adres URL elementu webhook jest funkcjonalny zgodnie ze standardami Acrobat Sign. Logikę niestandardową można dalej aktualizować zgodnie z własnymi wymaganiami.
Uzyskaj adres URL funkcji
- Kliknij przycisk Pobierz adres URL funkcji
Skopiuj adres URL i użyj go do tworzenia elementów webhook w programie Acrobat Sign.
Tworzenie funkcji AWS Lambda
Aby utworzyć funkcję AWS Lambda, zaloguj się do konsoli zarządzania AWS Management Console i wybierz usługę AWS Lambda z listy usług.
- Kliknij opcję Utwórz funkcję Lambda przy użyciu opcji „Utwórz od początku”
- Na stronie Konfiguruj funkcję wprowadź nazwę funkcji "lambdaWebhooks" i wybierz Node.js 4.3 jako środowisko wykonawcze
- W zakresie opcji Rola wybierz istniejącą rolę lub utwórz nową rolę z szablonu(ów)
- Jeśli wybrano Utwórz nową rolę z szablonu(ów) wprowadź nazwę roli (np. role-lambda) i wybierz Uprawnienia prostych mikroserwisów z listy Szablony zasad
- Kliknij przycisk Utwórz funkcję
- Na stronie nowej funkcji lamda AWS wybierz „Edytuj kod w wierszu" jako „Typ wpisu kodu", zachowaj index.handler jako element obsługi zdarzenia.
- Dodaj logikę, aby zarejestrować element webook Acrobat Sign
Przed pomyślnym zarejestrowaniem elementu webhook program Acrobat Sign sprawdza, czy adres URL elementu webhook podany w żądaniu rejestracji jest rzeczywiście przeznaczony do otrzymywania powiadomień, czy też nie. W tym celu, gdy program Acrobat Sign otrzymuje nowe żądanie rejestracji elementu webhook, najpierw kieruje żądanie weryfikacji na adres URL elementu webhook. To żądanie weryfikacji jest żądaniem HTTPS GET wysyłanym do adresu URL elementu webhook z niestandardowym nagłówkiem HTTP X-AdobeSign-ClientId. Wartość w tym nagłówku jest ustawiana na identyfikator klienta aplikacji, która żąda utworzenia/zarejestrowania elementu webhook. Aby pomyślnie zarejestrować element webhook, adres URL elementu webhook musi odpowiedzieć na to żądanie weryfikacji za pomocą kodu odpowiedzi 2XX ORAZ dodatkowo musi zwrócić tę samą wartość identyfikatora klienta za pomocą jednego z następujących dwóch. Należy również pamiętać, że takie samo zachowanie dla clientID jest oczekiwane, gdy adres URL elementu webhook otrzymuje powiadomienia POST.
Postępuj zgodnie z jednym z dwóch przypadków:
Przypadek 1: przekaż identyfikator klienta w X-AdobeSign-ClientId jako nagłówek odpowiedzi
- Przekaż X-AdobeSign-ClientId w nagłówku odpowiedzi. Jest to ten sam nagłówek, który został przekazany w żądaniu i musi być ponownie przywoływany w odpowiedzi.
Fragment kodu
W pliku index.js zastąp automatycznie wygenerowany fragment kodu następującym kodem:
- Przekaż X-AdobeSign-ClientId w nagłówku odpowiedzi. Jest to ten sam nagłówek, który został przekazany w żądaniu i musi być ponownie przywoływany w odpowiedzi.
|
Przykładowy kod JS węzła do pobrania identyfikatora klienta, sprawdzenia jego poprawności, a następnie zwrócenia go w nagłówku odpowiedzi |
|---|
|
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"); } } |
Przypadek 2: Przekaż identyfikator klienta w treści odpowiedzi za pomocą klucza xAdobeSignClientId
W treści odpowiedzi JSON z kluczem xAdobeSignClientId i jego wartością jest ten sam identyfikator klienta, który został wysłany w nagłówku żądania.
Fragment kodu
Zastąp plik Index.js następującą treścią:
|
Przykładowy kod JS węzła do pobrania identyfikatora klienta, sprawdzenia jego poprawności, a następnie zwrócenia go w nagłówku odpowiedzi |
|---|
|
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"); } } |
- Zapisz funkcję. Funkcja lambda została utworzona i jesteśmy prawie gotowi do użycia jej w elemencie webhook działającym w czasie rzeczywistym.
Konfiguracja bramy AWS API Gateway
Aby uczynić tę funkcję lambda publicznie dostępną za pomocą metody HTTP, musimy skonfigurować bramę AWS API Gateway, używając naszej funkcji (utworzonej powyżej) jako backendu dla API.
W konsoli zarządzania AWS wybierz Brama API Gateway z usług AWS i kliknij przycisk Utwórz API
- Na stronie Utwórz nowy interfejs API wybierz Nowy interfejs API i wprowadź webhooks jako nazwę API.
- Kliknij przycisk Utwórz API
- Wybierz listę rozwijaną Działania i zaznacz opcję Utwórz zasób
- Zaznacz opcję Skonfiguruj jako zasób proxy i wpisz validate jako Nazwę zasobu oraz {proxy+} w sekcji Ścieżka zasobu
- Pozostaw niezaznaczoną opcję Włącz API Gateway CORS i kliknij przycisk Utwórz zasób
- Zachowaj wybór Proxy funkcji Lambda jako Typ integracji i wybierz region, w którym utworzono funkcję Lambda na liście rozwijanej Region Lambda (prawdopodobnie jest to ten sam region, w którym tworzysz bramę API Gateway).
- Wpisz validate jako Funkcję lambda i kliknij przycisk Zapisz
- W oknie wyskakującym Dodaj uprawnienie do funkcji Lambda wybierz OK
Jeśli wszystkie powyższe kroki zostaną wykonane pomyślnie, zobaczysz coś takiego:
Wdrażanie interfejsu API
Następnym krokiem jest wdrożenie tego interfejsu API, aby był gotowy do użycia.
- Z listy rozwijanej Działania wybierz opcję Wdrażanie interfejsu API
- Wybierz [Nowy etap] na karcie Etap wdrożenia i wpisz prod (lub cokolwiek, czym chcesz zidentyfikować ten etap) w sekcji Nazwa etapu
- Kliknij przycisk Wdrożenie.
Interfejs API jest teraz gotowy do użycia, a adres URL wywołania można znaleźć w niebieskim polu, jak pokazano poniżej:
Zapamiętaj ten adres URL, ponieważ będzie on potrzebny do wprowadzenia jako adres URL elementu webhook czasu rzeczywistego.
Gotowe do użycia
Gotowe. Użyj powyższego adresu URL z dodatkiem "/{nodeJSfunctionName}" jako adresu URL elementu webhook w żądaniu API POST /webhooks. Po zweryfikowaniu zachowania adres URL elementu webhook jest funkcjonalny zgodnie ze
standardami Acrobat Sign. Logikę niestandardową można dalej aktualizować zgodnie z własnymi wymaganiami.
Opcje konfiguracji
Konfiguracja elementów Webhook wymaga zdefiniowania pięciu elementów:
- Nazwa — jest intuicyjną nazwą, którą inni administratorzy mogą łatwo zrozumieć.
- Zakres — jak szeroka jest sieć do przechwytywania elementów webhook? Konto i grupa są dostępne w interfejsie.
- Interfejs API obsługuje zakresy Konto, Grupa, Użytkownik i Zasoby.
- Można zdefiniować tylko jeden zakres na element webhook.
- URL — docelowy adres URL, do którego usługa Acrobat Sign wypchnęła ładunek JSON.
- Zdarzenia — wyzwalacz, który powoduje, że usługa Acrobat Sign tworzy JSON i wypycha na adres URL.
- Każde zdarzenie tworzy inny ładunek, odpowiedni do zdarzenia wyzwalającego.
- W jednym elemencie webhook można zawrzeć wiele zdarzeń.
- Parametry powiadomień — parametry powiadomień identyfikują sekcje Zdarzenia ładunku JSON, pozwalając wybrać tylko te sekcje Zdarzenia, które są ważne dla tego elementu webhook (a tym samym zmniejszając ilość niepotrzebnych danych wysyłanych na adres URL).
Po zdefiniowaniu elementu webhook kliknij przycisk Zapisz, a nowy element webhook zacznie reagować natychmiast na zdarzenia wyzwalacza.
Uwaga:
Skonfiguruj swój adres URL elementu webhook tak, aby odpowiadał na żądania weryfikacji webhook i powiadomienia webhook zgodnie z protokołem weryfikacji opisanym powyżej. Identyfikator klienta (identyfikator aplikacji), który zostanie wysłany do elementów webhook utworzonych z aplikacji internetowej Acrobat Sign, będzie miał postać — UB7E5BXCXY
Zakresy
- Konto: wszystkie subskrybowane zdarzenia występujące na koncie powodują uruchomienie mechanizmu push.
- Administratorzy kont mają uprawnienia do przeglądania wszystkich elementów webhook zdefiniowanych dla danego konta i grup w ramach tego konta.
- Grupa: wszystkie subskrybowane zdarzenia występujące w tej grupie powodują uruchomienie mechanizmu push. UWAGA: elementy webhook w zakresie grupy istnieją tylko dla tej grupy.
- Administratorzy grup będą widzieć tylko te elementy webhook, które są przypisane do ich grupy. Nie widzą oni elementów webhook poziomu konta ani elementów webhook przypisanych do innych grup.
- Konta z włączoną opcją Użytkownicy w wielu grupach będą widzieć opcję ustawienia Grupy, w której Zakres ma zostać zastosowany.
- Konto użytkownika: wszystkie subskrybowane zdarzenia dla konta użytkownika powodują uruchomienie mechanizmu push. Elementy webhook na poziomie użytkownika można tworzyć wyłącznie za pośrednictwem interfejsu API.
- Element webhook na poziomie zasobu: zostanie on utworzony dla konkretnego zasobu. Zdarzenia specyficzne dla tego zasobu będą przesyłane do adresu URL elementu webhook. Elementy webhook na poziomie zasobu można tworzyć wyłącznie za pośrednictwem interfejsu API.
URL
Adres URL elementu webhook to serwer nasłuchujący przychodzących komunikatów powiadamiających HTTPS POST, które są uruchamiane w momencie wystąpienia zdarzeń.
Ten adres URL jest potrzebny do subskrybowania zdarzeń za pomocą elementów webhook.
- Klient musi zawierać adres URL HTTPS, do którego program Acrobat Sign może wysłać POST. Ten adres URL musi być dostępny w publicznym Internecie.
- Na przykład adresy URI 127.0.0.1 i localhost nie będą działać.
- Punkt końcowy adresu URL musi nasłuchiwać na porcie 443 lub 8443 (określonym przez klienta podczas definiowania adresu URL wywołania zwrotnego).
- Upewnij się, że element webhook obsługuje żądania POST dla przychodzących powiadomień o zdarzeniach oraz żądania GET dla żądania weryfikacji.
- Adres URL nie powinien być blokowany przez zaporę sieciową.
Poniżej znajdują się zdarzenia, które mogą wyzwolić wysyłanie na adres URL elementu webhook, pogrupowane według obiektów i wymienione w kolejności znalezionej w interfejsie użytkownika.
Wartość po lewej stronie to wartość widoczna w interfejsie użytkownika usługi Acrobat Sign. Wartość po prawej stronie to nazwa elementu webhook w interfejsie API.
Aby uzyskać szczegółowe informacje dotyczące elementów webhook i ich ładunków, zobacz Podręcznik dla programistów aplikacji Acrobat Sign.
Umowy:
| Element interfejsu użytkownika | Nazwa elementu webhook |
| Wszystkie wydarzenia umowy | AGREEMENT_ALL |
| Utworzono umowę | AGREEMENT_CREATED |
| Umowa została wysłana | AGREEMENT_ACTION_REQUESTED |
| Zakończono pracę dotyczącą uczestnika umowy | AGREEMENT_ACTION_COMPLETED |
| Zakończono obieg pracy umowy | AGREEMENT_WORKFLOW_COMPLETED |
| Umowa wygasła | AGREEMENT_EXPIRED |
| Usunięto umowę | AGREEMENT_DOCUMENTS_DELETED |
| Umowa anulowana | AGREEMENT_RECALLED |
| Odrzucono umowę | AGREEMENT_REJECTED |
| Umowa udostępniona | AGREEMENT_SHARED |
| Umowa została oddelegowana | AGREEMENT_ACTION_DELEGATED |
| Zastąpiono uczestnika umowy | AGREEMENT_ACTION_REPLACED_SIGNER |
| Zmodyfikowano umowę | AGREEMENT_MODIFIED |
| Uznano modyfikację umowy | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
| Wiadomość e-mail dotycząca umowy wyświetlona | AGREEMENT_EMAIL_VIEWED |
| Wiadomość e-mail dotycząca umowy została zwrócona | AGREEMENT_EMAIL_BOUNCED |
| Nie udało się utworzyć umowy | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Umowa zsynchronizowana po zdarzeniu offline | AGREEMENT_OFFLINE_SYNC |
| Umowa przesłana przez nadawcę | AGREEMENT_UPLOADED_BY_SENDER |
| Umowa zarchiwizowana | AGREEMENT_VAULTED |
| Uczestnik umowy został uwierzytelniony za pomocą tożsamości społecznościowej | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
| Uczestnik umowy został uwierzytelniony za pomocą KBA | AGREEMENT_KBA_AUTHENTICATED |
| Wysłano przypomnienie o umowie | AGREEMENT_REMINDER_SENT |
| Nazwa sygnatariusza umowy została zmieniona przez sygnatariusza | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
| Elementy webhook umowy dostępne tylko za pośrednictwem interfejsu API | |
| nd. | AGREEMENT_EXPIRATION_UPDATED |
| nd. |
AGREEMENT_READY_TO_NOTARIZE |
| nd. |
AGREEMENT_READY_TO_VAULT |
Wyślij zbiorczo:
| Element interfejsu użytkownika | Nazwa elementu webhook |
| Wyślij zbiorczo – wszystkie zdarzenia | MEGASIGN_ALL |
| Wyślij zbiorczo – utworzone |
MEGASIGN_CREATED |
| Wyślij zbiorczo – udostępnione |
MEGASIGN_SHARED |
| Wyślij zbiorczo – przywołane |
MEGASIGN_RECALLED |
Formularze internetowe:
| Element interfejsu użytkownika | Nazwa elementu webhook |
| Formularz internetowy — wszystkie wydarzenia | WIDGET_ALL |
| Utworzono formularz internetowy |
WIDGET_CREATED |
| Włączono formularz internetowy |
WIDGET_ENABLED |
| Wyłączono formularz internetowy |
WIDGET_DISABLED |
| Zmodyfikowano formularz internetowy |
WIDGET_MODIFIED |
| Udostępniono formularz internetowy |
WIDGET_SHARED |
| Nie udało się utworzyć formularza internetowego |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Szablony biblioteki (tylko API):
| Element interfejsu użytkownika | Nazwa elementu webhook |
| n.d. | LIBRARY_DOCUMENT_ALL |
| n.d. | LIBRARY_DOCUMENT_CREATED |
| n.d. | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| n.d. | LIBRARY_DOCUMENT_MODIFIED |
Parametry powiadomień
Parametry powiadomień umożliwiają dostosowanie zawartości pliku JSON do określonych elementów zdarzenia.
Na przykład w przypadku zdarzenia Zastąpiono uczestnika umowy możesz chcieć tylko Informacje o umowie i Informacje o użytkowniku, pomijając Informacje o dokumencie i zmniejszając całkowitą objętość pliku JSON wysłanego na adres URL elementu webhook.
- Umowa
- Informacje o umowie — szczegółowe informacje o umowie na podstawie statusu umowy w momencie wystąpienia zdarzenia wyzwalającego.
- Informacje o dokumencie umowy — zawiera wszelkie informacje o dokumentach wygenerowane w wyniku zdarzenia.
- Informacje o uczestniku umowy — zawiera wszelkie informacje o uczestniku wynikające ze zdarzenia.
- Dokument podpisany w ramach umowy — udostępnia podpisany plik PDF.
- Dotyczy Obieg umowy zakończono pomyślnie i Wszystkie wydarzenia umowy.
- Wyślij zbiorczo
- Informacje o funkcji Wyślij zbiorczo — szczegółowe informacje o obiekcie wysyłania zbiorczego, który wywołał zdarzenie.
- Formularz internetowy
- Informacje o widżecie — szczegółowe informacje o formularzu internetowym, który wywołał zdarzenie.
- Informacje o dokumentach widżetu — informacje o dokumencie związane z formularzem internetowym.
- Informacje o uczestnikach widżetu — informacje o zdefiniowanych uczestnikach w formularzu internetowym.
Dwukierunkowe uwierzytelnianie SSL
Dwukierunkowy protokół SSL, często określany nazwą „Client-Side SSL” lub „wspólny TLS”, to tryb protokołu SSL, w którym zarówno serwer, jak i klient (przeglądarka internetowa) przedstawiają certyfikaty w celu wzajemnej identyfikacji.
Administratorzy kont mogą skonfigurować certyfikat po stronie klienta na stronie Ustawienia zabezpieczeń.
Program Acrobat Sign weryfikuje certyfikaty SSL podczas dostarczania ładunków do adresu URL elementu webhook. Elementy webhook, które nie przejdą pomyślnie weryfikacji certyfikatu SSL, nie będą w stanie dostarczyć ładunku JSON.
Użyj dwukierunkowego protokołu SSL, aby uwierzytelnić klienta (Acrobat Sign) i usługę nasłuchiwania, aby zapewnić, że tylko Acrobat Sign może dotrzeć do adresu URL elementu webhook.
Jeśli element webhook został utworzony przez aplikację partnerską, będzie on używał certyfikatu klienta (jeśli jest dostępny) z konta aplikacji partnerskiej w celu identyfikacji podczas wysyłania powiadomień dotyczących elementów webhook.
Poniżej przedstawiono najczęściej zadawane pytania dotyczące procesu weryfikacji serwera internetowego i weryfikacji certyfikacji klienta.
Weryfikacja serwera internetowego
Podczas rejestracji elementu webhook aplikacja Acrobat Sign weryfikuje adres URL serwera elementu webhook.
Klienci nie będą w stanie zarejestrować elementu webhook, jeśli nie będzie można nawiązać połączenia z adresem URL wywołania zwrotnego elementu webhook z poziomu aplikacji Acrobat Sign.
Nie.
Adres URL wywołania zwrotnego elementu webhook może być tylko adresem HTTPS na porcie 443 lub 8443.
Acrobat Sign blokuje wychodzący ruch HTTPS do wszystkich innych portów.
Dobrym sposobem sprawdzenia certyfikatu serwera jest użycie narzędzia DigiCert® SSL Installation Diagnostics Tool.
Wprowadź tylko nazwę hosta, np. www.digicert.com
Typowe problemy:
- Problem: Korzystanie z niezaufanego urzędu certyfikacji lub z certyfikatu podpisywanego automatycznie
Rozwiązanie: Użyj certyfikatu SSL wystawionego przez publiczny urząd certyfikacji dla serwera wywołania zwrotnego elementu webhook.
- Problem: Serwer nie wysyła certyfikatu pośredniego
Rozwiązanie: Zainstaluj certyfikaty pośrednie na serwerze wywołania zwrotnego elementu webhook.
Szczegółowe informacje: https://www.digicert.com/kb/ssl-certificate-installation.htm.
Weryfikacja certyfikatu klienta
Aby skonfigurować dwukierunkowy protokół SSL dla elementu webhook, administrator musi przesłać plik .p12 (lub .pfx) zawierający klucz prywatny. Plik jest przechowywany bezpiecznie na koncie klienta, a administrator ma pełną kontrolę i może go usunąć w dowolnym momencie.
W konfiguracji dwukierunkowego elementu webhook Acrobat Sign jest rozmówcą/klientem i wymaga klucza prywatnego w celu udowodnienia, że połączenie zostało wykonane przez aplikację Acrobat Sign w imieniu konta klienta.
-
Sprawdź, czy jest włączony dwukierunkowy protokół SSL
Na serwerze wywołania zwrotnego elementu webhook musi być włączony dwukierunkowy protokół SSL.
Przy użyciu dowolnej przeglądarki sieci Web połącz się z adresem URL wywołania zwrotnego elementu webhook. Powinien wyświetlić się następujący komunikat:
400 Błędne żądanie Nie wysłano wymaganego certyfikatu SSL
Oznacza to, że serwer oczekuje od klienta wysłania certyfikatów klienta (tj. dla serwera jest włączony dwukierunkowy protokół SSL).
Jeśli powyższy komunikat nie jest widoczny, dwukierunkowy protokół SSL nie jest włączony.
Uwaga:Można użyć usługi Postman i zrealizować żądanie POST dla adresu URL wywołania zwrotnego elementu webhook. Uzyskany wynik powinien być podobny.
-
Poświadczenie klienta może stanowić certyfikat podpisany automatycznie lub certyfikat wystawionym przez urząd certyfikacji. Jednak musi on być minimalnie zgodny z następującymi rozszerzeniami X.509 v3:
Rozszerzenie X.509 v3
Wartość
ExtendedKeyUsage
clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
Certyfikat klienta musi być plikiem PKCS12 z rozszerzeniem .p12 lub .pfx i musi zawierać zarówno certyfikat klienta (aby serwer mógł zweryfikować tożsamość klienta), jak i klucz prywatny klienta (aby klient mógł cyfrowo podpisywać wiadomości dla serwera w celu weryfikacji podczas uzgadniania SSL).
Użyj polecenia opensslw celu zweryfikowania pliku p12 (pfx):
openssl pkcs12 -info -in outfile.p12
Należy zażądać hasła dla klucza prywatnego. Dane wyjściowe powinny zawierać zarówno certyfikaty, jak i zaszyfrowany klucz prywatny, np:
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-----Certyfikaty powinny obejmować co najmniej certyfikat podmiotu końcowego i certyfikaty pośrednie. Najlepiej, aby był również ujęty certyfikat głównego urzędu certyfikacji.
Komunikat:Plik .p12 lub .pfx musi być chroniony hasłem.
-
Utwórz automatycznie podpisywany certyfikat klienta (opcjonalnie)
W zależności od potrzeb certyfikaty klienta mogą być wystawiane przez urząd certyfikacji lub podpisywane automatycznie.
Aby wygenerować automatycznie podpisywany certyfikat klienta, użyj następującego polecenia openssl:
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Uwaga:Pliki wynikowe należy przechowywać jako tajne, ponieważ stanowią one automatycznie podpisywane certyfikaty urzędu certyfikacji.
Następnie wygeneruj plik .p12 klienta:
- Wygeneruj klucz prywatny dla klienta SSL:
openssl genrsa -out client.key 2048
- Użyj klucza prywatnego klienta, aby wygenerować żądanie certyfikatu:
openssl req -new -key client.key -out client.req
- Wystaw certyfikat klienta przy użyciu żądania certyfikatu i certyfikatu urzędu certyfikacji/klucza:
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Skonwertuj certyfikat klienta i klucz prywatny do formatu pkcs#12 w celu użycia przez przeglądarki:
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Usuń klucz prywatny klienta, certyfikat klienta i pliki żądań klienta, ponieważ plik pkcs12 zawiera już wszystkie niezbędne elementy.
rm client.key client.cer client.req
- Wygeneruj klucz prywatny dla klienta SSL:
-
- Użyj usługi Postman, aby załadować plik PFX klienta w sekcji Ustawienia > Certyfikaty.
- Wybierz opcję Dodaj certyfikat, aby dodać certyfikat klienta.
- Skonfiguruj nagłówek HTTP dla parametru x-adobesign-clientid:
Po skonfigurowaniu wyślij żądanie POST na adres URL wywołania zwrotnego elementu webhook.
Powinna zostać zwrócona odpowiedź 200.
-
Dlaczego aplikacja Acrobat Sign odrzuca mój plik PFX nawet po zweryfikowaniu go w usłudze Postman?
Jeśli po zrealizowaniu powyższego procesu weryfikacji pliku pfx usługa Acrobat Sign nadal odrzuca ten plik, prawdopodobnie został wygenerowany za pomocą narzędzia firmy Microsoft, które może wygenerować niestandardowy plik PKCS12.
W takim przypadku użyj poniższych poleceń openssl, aby wyodrębnić certyfikaty i klucz prywatny z pliku pfx, a następnie wygeneruj poprawnie sformatowany plik PKCS12:
// Extract certificates and private key from pfx file 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 // Create new PKCS12 file openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Włączanie i wyłączanie
Dostęp do funkcji elementy webhook jest domyślnie włączony dla kont planów korporacyjnych.
Administratorzy poziomu grupy mogą tworzyć lub kontrolować elementy webhool działające tylko w obrębie ich grupy.
Dostęp do strony elementu webhook można znaleźć w lewej części menu administratora: Konto > Elementy webhook
Aktywacja elementu webhook
Gdy element webhook jest tworzony po raz pierwszy, ma status Aktywny.
Na stronie elementu webhook w programie Acrobat Sign domyślnie widoczne są aktywne elementy webhook.
Aby aktywować nieaktywny element webhook:
- Kliknij ikonę Opcje (trzy poziome linie) po prawej stronie wiersza nagłówka elementu webhook i wybierz Pokaż wszystkie elementy webhook
- Zaznacz nieaktywny element webhook pojedynczym kliknięciem
- W ten sposób opcje dla elementu webhook są widoczne tuż pod wierszem nagłówka
- Kliknij przycisk Aktywuj
Aktywny element webhook zacznie wysyłać dane do docelowego adresu URL, gdy tylko zostanie wywołane kolejne zdarzenie.
Dezaktywowanie elementu webhook
Aby dezaktywować element webhook:
- Przejdź do strony Elementy webhook
- Kliknij raz element webhook, który chcesz dezaktywować
- Wybierz opcję Dezaktywuj z pozycji menu pod wierszem nagłówka
- Po dezaktywacji element webhook ma status Nieaktywny
Wyświetlanie lub edytowanie elementu webhook
Elementy webhook można edytować i zapisywać w dowolnym momencie, a po zapisaniu nowej konfiguracji zmiana wchodzi w życie natychmiast.
Edytować można tylko Zdarzenia i Parametry powiadomień.
Jeśli Nazwa, Zakres lub Adres URL mają zostać zmienione, konieczne będzie utworzenie nowego elementu webhook.
Aby edytować parametry elementu webhook:
- Przejdź do strony Elementy webhook
- Kliknij raz element webhook, który chcesz edytować
- Kliknij opcję Wyświetl/edytuj pod wierszem nagłówka
- Wprowadź wszelkie niezbędne zmiany i kliknij Zapisz
Usuwanie elementu webhook
Element webhook można usunąć w dowolnym momencie.
Usunięcie elementu webhook powoduje jego zniszczenie w systemie, więc nie ma możliwości odzyskania usuniętego elementu webhook.
Elementy webhook nie muszą być najpierw dezaktywowane.
Aby usunąć element webhook:
- Przejdź do sekcji Elementy webhook
- Wybierz element webhook, który chcesz usunąć, klikając go raz
- Kliknij opcję Usuń pod wierszem nagłówka
- Zostanie wyświetlone wyzwanie potwierdzające, że element webhook ma zostać usunięty. Kliknij przycisk OK.
Sprawdzone metody
- Subskrybuj określone, potrzebne zdarzenia, aby ograniczyć liczbę żądań HTTPS do serwera — im bardziej precyzyjne elementy webhook, tym mniej objętości należy przesiać.
- Odporność na powielanie — jeśli masz więcej niż jedną aplikację korzystającą z tego samego adresu URL elementu webhook i tego samego użytkownika zmapowanego do każdej aplikacji, to to samo zdarzenie będzie wysyłane do Twojego elementu webhook wielokrotnie (raz na aplikację). W niektórych przypadkach element webhook może otrzymywać zduplikowane zdarzenia. Twoja aplikacja elementu webhook powinna być na to odporna i deduplikować według identyfikatora zdarzenia.
- Zawsze szybko reaguj na elementy webhook — Twoja aplikacja ma tylko pięć sekund na zareagowanie na żądania elementów webhook. W przypadku żądania weryfikacji rzadko stanowi to problem, ponieważ aplikacja nie musi wykonywać żadnych czynności, aby na nie odpowiedzieć. Jednak w przypadku żądań powiadomień aplikacja zwykle wykonuje coś, co wymaga czasu w odpowiedzi na żądanie. Zaleca się pracę nad oddzielnym wątkiem lub asynchroniczne używanie kolejki, aby zapewnić odpowiedź w ciągu pięciu sekund.
- Zarządzaj współbieżnością — gdy użytkownik dokonuje wielu zmian w szybkim tempie, Twoja aplikacja prawdopodobnie otrzyma wiele powiadomień dotyczących tego samego użytkownika mniej więcej w tym samym czasie. Jeśli nie zachowasz ostrożności w zarządzaniu współbieżnością, Twoja aplikacja może przetwarzać te same zmiany dla tego samego użytkownika więcej niż jeden raz. Aby skorzystać z elementów webhook programu Acrobat Sign, należy dobrze zrozumieć sposób wykorzystania tych informacji. Należy zadać następujące pytania:
- Jakie dane chcesz zwrócić w ładunku?
- Kto będzie uzyskiwał dostęp do tych informacji?
- Jakie decyzje lub raporty będą generowane?
- Zalecenia dotyczące otrzymywania podpisanego dokumentu — istnieje kilka czynników, które należy wziąć pod uwagę przy określaniu sposobu otrzymywania podpisanego pliku PDF z programu Acrobat Sign w systemie zarządzania dokumentami.
Chociaż całkowicie dopuszczalne jest wybranie opcji Dokument podpisany w ramach umowy podczas tworzenia elementu webhook, można rozważyć użycie interfejsu API Acrobat Sign do pobierania dokumentów po otrzymaniu zdarzenia wyzwalającego (takiego jak status umowy Gotowa).
Kwestie, o których należy pamiętać...
Ograniczenie rozmiaru JSON
Rozmiar ładunku JSON jest ograniczony do 10 MB.
Jeśli zdarzenie wygeneruje większy ładunek, zostanie wywołany element webhook, ale atrybuty parametrów warunkowych, jeśli występują w żądaniu, zostaną usunięte, aby zmniejszyć rozmiar ładunku.
Wartość „ConditionalParametersTrimmed” zostanie zwrócona w odpowiedzi, gdy tak się stanie, aby poinformować klienta, że informacja conditionalParameters została usunięta.
„conditionalParametersTrimmed” to obiekt typu array zawierający informacje o kluczach, które zostały przycięte.
Obcięcie zostanie wykonane w następującej kolejności:
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
Najpierw zostaną skrócone podpisane dokumenty, następnie informacje o uczestniku, informacje o dokumencie, a na końcu informacje szczegółowe.
Może się to zdarzyć na przykład w przypadku zdarzenia zakończenia umowy, jeśli zawiera ono również podpisany dokument (zakodowany w standardzie base 64) lub w przypadku umowy zawierającej wiele pól formularza
Powiadomienia dotyczące elementu webhook
Elementy webhook programu Acrobat Sign dostarczają powiadomień, które mają zastosowanie do wszystkich uczestników umowy, jeśli dla danego użytkownika, jego grupy lub konta skonfigurowano element webhook.
Zdarzenia związane z umową są przetwarzane w taki sposób, że jeśli istnieje element webhook skonfigurowany dla odpowiedniego uczestnika tego zdarzenia, wysyłane jest powiadomienie na adres URL tego elementu webhook. Innymi słowy, elementy webhook są wyzwalane dla zdarzeń we wszystkich stosownych umowach, nawet tych spoza grupy lub konta, w którym element webhook jest skonfigurowany.
Powiadomienia są dostarczane tylko dla tych zdarzeń, w których uczestnik bierze udział. Na przykład Nadawca umowy otrzymuje prawie wszystkie powiadomienia, natomiast Odbiorcy otrzymują powiadomienia tylko od początku swojego udziału w umowie i tylko w odniesieniu do tych zdarzeń, w których biorą udział.
Powiadomienia elementów webhook są zgodne z obecnym modelem uwierzytelniania i widoczności samego programu Acrobat Sign, co oznacza, że użytkownicy będą mieli dostęp do umowy tylko wtedy, gdy rozpocznie się ich udział w umowie.
Nadawca wysyła umowę do podpisu do trzech sygnatariuszy.
- Dla konta Nadawcy skonfigurowano poziom konta WebhookX.
- Sygnatariusz1 jest użytkownikiem tego samego konta co Nadawca, ale należy do innej Grupy, a dla tej grupy skonfigurowano konto WehbhookY.
- Sygnatariusz2 jest członkiem innego konta, a dla konta Sygnatariusz2 jest skonfigurowany WebhookZ na poziomie konta.
- Sygnatariusz3 jest członkiem tego samego konta co Nadawca.
Nadawca wysyła umowę: WebhookX wyzwala się przy „Umowa została utworzona” i „Umowa została wysłana”, natomiast WebhookY wyzwala się przy „Umowa została wysłana”.
Sygnatariusz1 składa podpis: WebhookX wyzwala się przy „Zakończono pracę dotyczącą uczestnika umowy” i „Umowa została wysłana”, WebhookY wyzwala się przy „Zakończono pracę dotyczącą uczestnika umowy” i WebhookZ wyzwala się przy „Umowa została wysłana”.
Sygnatariusz2 składa podpis: WebhookX wyzwala się przy „Zakończono pracę dotyczącą uczestnika umowy” i „Umowa została wysłana”, natomiast WebhookZ wysyła powiadomienie dla „Zakończono pracę dotyczącą uczestnika umowy”.
Sygnatariusz3 składa podpis: WebhookX wyzwala się przy „Zakończono pracę dotyczącą uczestnika umowy” i „Zakończono obieg pracy umowy”, WebhookY wyzwala się przy „Zakończono obieg pracy umowy” oraz WebhookZ wyzwala się przy „Zakończono obieg pracy umowy”.
Ponów próbę, gdy usługa nasłuchu nie działa
Jeśli docelowy adres URL elementu webhook nie działa z jakiegokolwiek powodu, usługa Acrobat Sign doda plik JSON do kolejki i ponowi próbę wypchnięcia w cyklu progresywnym przez 72 godziny.
Niedostarczone zdarzenia zostają utrwalone w kolejce ponownych prób i w ciągu następnych 72 godzin dokłada się wszelkich starań, aby dostarczyć powiadomienia w kolejności, w jakiej wystąpiły.
Strategia ponownych prób dostarczenia powiadomień polega na podwojeniu czasu między próbami, począwszy od 1-minutowego odstępu, który wzrasta do 12 godzin, co daje 15 ponownych prób w ciągu 72 godzin.
Jeśli odbiorca elementu webhook nie odpowie w ciągu 72 godzin, a w ciągu ostatnich siedmiu dni nie było żadnych udanych powiadomień, element webhook zostanie wyłączony. Na ten adres URL nie będą wysyłane żadne powiadomienia do czasu ponownego uaktywnienia elementu webhook.
Wszystkie powiadomienia od momentu wyłączenia elementu webhook do momentu jego ponownego włączenia zostaną utracone.
