Podręcznik użytkownika Anuluj

Przegląd usługi Acrobat Sign Webhook

 

Podręcznik Adobe Acrobat Sign

Nowości

Pierwsze kroki

Administrowanie

Wysyłanie i podpisywanie umów oraz zarządzanie nimi

Zaawansowane możliwości umów i obiegów pracy

Integracja z innymi produktami

Programista Acrobat Sign

Pomoc techniczna i rozwiązywanie problemów

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

Przed skonfigurowaniem elementów webhook należy upewnić się, że sieć akceptuje zakresy IP wymagane dla funkcjonalności.

 

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:

Wymagania wstępne

Aby usługa działała, należy zezwolić na zakresy IP dla elementów webhook za pośrednictwem zabezpieczeń sieciowych.

Starsza usługa adresu URL wywołania zwrotnego w REST v5 wykorzystuje te same zakresy adresów IP, co usługa webhook.

Administratorzy mogą zalogować się na stronie Adobe Admin Console, aby dodać użytkowników. Po zalogowaniu przejdź do menu administratora i przewiń w dół do sekcji Elementy webhook.

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.

Włączanie i wyłączanie

Dostęp do funkcji elementy webhook jest domyślnie włączony dla kont na poziomie przedsiębiorstwa.

Administratorzy poziomu grupy mogą tworzyć lub kontrolować elementy webhook działające tylko w obrębie ich grupy.

Dostęp do strony elementu webhook można znaleźć w lewej części menu Administrator.

Przejście do karty webhooks

Ograniczenie szybkości oparte na współbieżności

Zdarzenia tworzenia elementu webhook (i wywołania zwrotnego) i powiadomień są ograniczone w liczbie jednoczesnych powiadomień, które są aktywnie dostarczane klientowi z systemu Acrobat Sign. Ten limit dotyczy konta, aby uwzględnić wszystkie grupy na koncie.
Ten rodzaj ograniczenia szybkości zapobiega zużywaniu przez jedno źle zaprojektowane konto nieproporcjonalnej ilości zasobów serwera, co negatywnie wpływa na wszystkich innych klientów w tym środowisku serwerowym.

Obliczono liczbę jednoczesnych zdarzeń na konto w celu zapewnienia, że konta ze stabilnymi elementami webhook będą otrzymywać powiadomienia w jak najkrótszym czasie i rzadko powinny napotkać sytuację, w której powiadomienia są opóźnione z powodu zbyt dużej liczby żądań. Obecne progi to:

Działanie
(zdarzenie)

Maksymalna liczba
jednoczesnych
zdarzeń

Opis

Tworzenie elementów webhook

10

Na jedno konto dozwolonych jest maksymalnie 10 jednoczesnych żądań utworzenia elementów webhook.
Żądania przekraczające ten limit będą skutkować kodem odpowiedzi 429 TOO_MANY_REQUESTS.
 

Powiadomienie elementu webhook/wywołania zwrotnego

30

Na konto dozwolone jest maksymalnie 30 jednoczesnych powiadomień elementów webhook i wywołań zwrotnych.
Powiadomienia przekraczające ten limit będą ponawiane zgodnie z wykładniczym przesunięciem, dopóki nie zostaną dostarczone.

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 Acrobat Sign dostarczają powiadomienia do nadawcy umowy i wszelkie elementy webhook skonfigurowane w grupie, z której wysłano umowę. Elementy webhook w zakresie konta odbierają wszystkie zdarzenia.

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.

Pomoc dostępna szybciej i łatwiej

Nowy użytkownik?