Konfigurowanie i zarządzanie standardowymi webhookami w Enquete

Standardowe webhooki umożliwiają Enquete automatyczne wysyłanie informacji związanych z ankietami do innej aplikacji po wystąpieniu wybranego zdarzenia.

Na przykład, gdy respondent prześle lub ukończy ankietę, Enquete może wysłać dane zdarzenia bezpośrednio do systemu zarządzania relacjami z klientami, platformy raportowej, wewnętrznej bazy danych, aplikacji pomocy technicznej, platformy marketingowej lub innej usługi zewnętrznej.

Pomaga to organizacji automatyzować przepływy pracy i przenosić dane ankietowe między systemami bez konieczności wielokrotnego eksportowania odpowiedzi lub ręcznego przesyłania informacji.

Ten przewodnik wyjaśnia, jak tworzyć, konfigurować, testować, monitorować i zarządzać standardowymi webhookami z poziomu interfejsu Enquete.

 

Czym jest standardowy webhook?

Standardowy webhook to automatyczne połączenie między Enquete a aplikacją zewnętrzną.

Gdy w wybranej ankiecie wystąpi zdarzenie, Enquete wysyła żądanie HTTP POST na adres URL punktu końcowego skonfigurowany w subskrypcji webhooka.

W zależności od przepływu pracy organizacji webhook może służyć do:

• Wysyłania nowych odpowiedzi z ankiet do systemu CRM.
• Zapisywania danych ankietowych w wewnętrznej bazie danych.
• Powiadamiania zespołu pomocy technicznej lub obsługi klienta.
• Uruchamiania procesu raportowania lub analizy.
• Tworzenia lub aktualizowania rekordu w innej aplikacji.
• Uruchamiania niestandardowego wewnętrznego procesu biznesowego.

Każdy standardowy webhook jest powiązany z określoną ankietą i określonym typem zdarzenia. Pozwala to kontrolować, które działania powodują wysłanie danych oraz dokąd informacje są przekazywane.

 

Przed utworzeniem webhooka

Przed skonfigurowaniem standardowego webhooka upewnij się, że zespół techniczny przygotował:

• Publicznie dostępny punkt końcowy HTTPS.
• Serwer zdolny do odbierania żądań HTTP POST.
• Proces odczytywania treści żądań JSON.
• Bezpieczne miejsce do przechowywania sekretu webhooka.
• Proces weryfikacji podpisów webhooka.
• Metodę zapobiegania wielokrotnemu przetwarzaniu tego samego zdarzenia.

Punkt końcowy odbierający powinien szybko odpowiedzieć po zaakceptowaniu żądania. Długotrwałe operacje powinny być zwykle przekazywane do kolejki lub systemu przetwarzania w tle po zwróceniu przez punkt końcowy odpowiedzi oznaczającej powodzenie.

Przed wdrożeniem punktu końcowego odbierającego programiści powinni zapoznać się z oficjalną dokumentacją webhooków.

 

Jak otworzyć standardowe webhooki

Krok 1: Otwórz Integracje

Na pulpicie Enquete wybierz Integracje w górnym menu.

Krok 2: Wybierz Standardowe webhooki

Otwórz Standardowe webhooki z dostępnych opcji integracji.

Przegląd standardowych webhooków wyświetla wszystkie subskrypcje webhooków dostępne na koncie.

Na tej stronie można:

• Utworzyć nowy webhook.
• Wyświetlić istniejące subskrypcje webhooków.
• Edytować ustawienia webhooków.
• Wyświetlać i kopiować sekrety webhooków.
• Wysyłać dostawy testowe.
• Przeglądać dzienniki dostaw.
• Aktywować lub dezaktywować webhook.
• Usunąć webhook.

 

Jak utworzyć standardowy webhook

Krok 1: Kliknij Dodaj webhook

W przeglądzie standardowych webhooków kliknij Dodaj webhook.

Otworzy się formularz konfiguracji.

Krok 2: Wprowadź adres URL punktu końcowego

Wprowadź punkt końcowy HTTPS, do którego Enquete ma wysyłać dostawy webhooka.

Na przykład:

https://example.com/api/enquete/webhook

Punkt końcowy musi być publicznie dostępny i umożliwiać odbieranie żądań HTTP POST.

Adresy localhost, prywatne adresy URL środowisk programistycznych oraz strony wymagające interaktywnego logowania nie mogą odbierać dostaw webhooków z Enquete.

Krok 3: Dodaj opis

Wprowadź opis jasno wyjaśniający przeznaczenie webhooka.

Na przykład:

Wysyłaj ukończone odpowiedzi dotyczące satysfakcji klientów do naszego systemu CRM

Jasny opis ułatwia późniejsze zidentyfikowanie webhooka, szczególnie gdy organizacja zarządza kilkoma subskrypcjami.

Krok 4: Wybierz ankietę

Wybierz ankietę, której zdarzenia mają uruchamiać webhook.

Subskrypcja standardowego webhooka jest powiązana z jedną ankietą. Aby wysyłać zdarzenia z kilku ankiet, utwórz osobną subskrypcję webhooka dla każdej ankiety.

Krok 5: Wybierz typ zdarzenia

Wybierz zdarzenie, które ma uruchamiać dostawę webhooka.

Zdarzenia dostępne w interfejsie standardowych webhooków mogą obejmować:

• survey.new.response
• survey.response.completed

Dostępne zdarzenia mogą zależeć od bieżącej konfiguracji Enquete oraz funkcji włączonych na koncie.

Krok 6: Wybierz stan aktywacji

Wybierz, czy webhook ma być aktywny natychmiast.

Gdy webhook jest aktywny, Enquete wysyła dostawy za każdym razem, gdy wystąpi wybrane zdarzenie.

Gdy webhook jest nieaktywny, jego konfiguracja pozostaje dostępna, ale dostawy zdarzeń na żywo są wstrzymane.

Webhook można pozostawić nieaktywny, podczas gdy zespół techniczny kończy przygotowywanie lub testowanie punktu końcowego odbierającego.

Krok 7: Zapisz webhook

Kliknij Zapisz, aby utworzyć subskrypcję webhooka.

Nowy webhook pojawi się w przeglądzie standardowych webhooków i będzie można go natychmiast przetestować.

 

Jak zarządzać sekretem webhooka

Każdy standardowy webhook ma sekret. Aplikacja odbierająca wykorzystuje go do potwierdzenia, że przychodzące żądanie rzeczywiście pochodzi z Enquete.

Sekret webhooka należy traktować jak hasło lub prywatne dane uwierzytelniające interfejsu API.

Krok 1: Wyświetl sekret

Znajdź webhook w przeglądzie i kliknij ikonę oka.

Sekret zostanie wyświetlony tymczasowo.

Krok 2: Skopiuj sekret

Kliknij ikonę schowka, aby skopiować sekret.

Ze względów bezpieczeństwa sekret zostanie automatycznie ponownie ukryty po około dziesięciu sekundach.

Krok 3: Przechowuj sekret bezpiecznie

Przekaż sekret programiście odpowiedzialnemu za punkt końcowy odbierający i przechowuj go w bezpiecznym miejscu po stronie serwera, takim jak:

• Zmienna środowiskowa.
• Zaszyfrowana konfiguracja aplikacji.
• Menedżer sekretów w chmurze.
• Chroniony magazyn danych uwierzytelniających.

Nie przechowuj sekretu w kodzie JavaScript frontendu, publicznych repozytoriach, zrzutach ekranu, udostępnionych dokumentach ani wiadomościach pomocy technicznej dostępnych dla nieupoważnionych użytkowników.

 

Jak przetestować webhook

Każdy webhook należy przetestować przed wykorzystaniem go w działającym przepływie pracy.

Dostawa testowa potwierdza, że punkt końcowy jest osiągalny i że serwer odbierający zwraca odpowiednią odpowiedź.

Krok 1: Znajdź webhook

Znajdź subskrypcję webhooka w przeglądzie standardowych webhooków.

Krok 2: Wyślij dostawę testową

Kliknij ikonę błyskawicy w wierszu webhooka.

Enquete wyśle żądanie testowe do skonfigurowanego punktu końcowego.

Krok 3: Sprawdź wynik

Powiadomienie wyświetlane na stronie pokaże status HTTP zwrócony przez punkt końcowy.

Pomyślna dostawa zazwyczaj zwraca kod stanu w zakresie od 200 do 299, na przykład:

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content

Jeśli test zakończy się niepowodzeniem, otwórz dzienniki dostaw, aby sprawdzić status odpowiedzi, treść odpowiedzi, informacje o błędzie i czas trwania żądania.

 

Jak edytować webhook

Istniejący webhook można zaktualizować, gdy zmieni się jego punkt końcowy, ankieta, typ zdarzenia, opis lub stan aktywacji.

Krok 1: Kliknij Edytuj

Znajdź webhook i wybierz działanie Edytuj.

Krok 2: Zaktualizuj ustawienia

Możesz zaktualizować ustawienia takie jak:

• Adres URL punktu końcowego.
• Opis webhooka.
• Wybrana ankieta.
• Typ zdarzenia.
• Stan aktywny lub nieaktywny.

Krok 3: Zapisz zmiany

Po wprowadzeniu zmian zapisz webhook.

Zaktualizowana konfiguracja będzie używana podczas przyszłych dostaw.

Po zmianie adresu URL punktu końcowego, ankiety lub typu zdarzenia zawsze wyślij kolejną dostawę testową.

 

Jak wyświetlić dzienniki dostaw

Dzienniki dostaw pokazują żądania wysłane przez Enquete do punktu końcowego oraz odpowiedzi zwrócone przez serwer odbierający.

Używaj tych dzienników do monitorowania stanu integracji i badania nieudanych dostaw.

Krok 1: Otwórz dzienniki

Znajdź subskrypcję webhooka i kliknij ikonę Wyświetl dzienniki obok przycisku usuwania.

Krok 2: Filtruj historię dostaw

Dostawy można filtrować według:

• Wszystkie
• Zakończone powodzeniem
• Nieudane

Krok 3: Sprawdź dostawę

Rozwiń wpis dostawy, aby przejrzeć dostępne informacje diagnostyczne.

Rekord dostawy może zawierać:

• Ładunek danych żądania.
• Status odpowiedzi HTTP.
• Treść odpowiedzi zwróconej przez serwer odbierający.
• Komunikat o błędzie.
• Czas trwania dostawy w milisekundach.
• Numer próby dostawy.
• Unikalny identyfikator dostawy.

Dzienniki dostaw są szczególnie przydatne po:

• Utworzeniu nowego webhooka.
• Zmianie adresu URL punktu końcowego.
• Wdrożeniu aktualizacji aplikacji odbierającej.
• Zmianie ustawień zapory sieciowej lub serwera.
• Badaniu brakujących danych ankietowych.
• Badaniu wolnych lub nieudanych dostaw.

 

Informacje o nagłówkach webhooków

Każde żądanie webhooka zawiera nagłówki, które pomagają aplikacji odbierającej zidentyfikować, zweryfikować i śledzić dostawę.

Nagłówek	Opis
X-Enquete-Signature	Zawiera podpis używany do weryfikacji, czy żądanie pochodzi z Enquete.
X-Enquete-Event	Identyfikuje typ zdarzenia, które uruchomiło dostawę.
X-Enquete-Delivery	Zawiera unikalny identyfikator dostawy używany do śledzenia i zapobiegania wielokrotnemu przetwarzaniu.

Zespół techniczny powinien używać nagłówka podpisu do uwierzytelniania przychodzących żądań, a nagłówka dostawy do zapobiegania wielokrotnemu przetwarzaniu tego samego zdarzenia.

Dokładny format podpisu, schemat ładunku danych i przykłady implementacji można znaleźć w oficjalnej dokumentacji webhooków.

 

Informacje o zduplikowanych dostawach

Próba dostarczenia webhooka może zostać podjęta więcej niż jeden raz, jeśli pierwsze żądanie zakończy się niepowodzeniem, przekroczy limit czasu lub nie zwróci odpowiedzi oznaczającej powodzenie.

Oznacza to, że aplikacja odbierająca musi być w stanie rozpoznać i bezpiecznie zignorować dostawę, która została już przetworzona.

Każde żądanie zawiera unikalną wartość w nagłówku X-Enquete-Delivery.

Zespół techniczny powinien używać tej wartości jako klucza idempotencji.

Typowy proces zapobiegania wielokrotnemu przetwarzaniu wygląda następująco:

1. Odczytaj wartość X-Enquete-Delivery.
2. Sprawdź, czy identyfikator dostawy został już przetworzony.
3. Jeśli został już przetworzony, zwróć odpowiedź oznaczającą powodzenie bez ponownego wykonywania działania.
4. Jeśli nie został jeszcze przetworzony, zapisz identyfikator dostawy i przetwórz zdarzenie.

Identyfikatory przetworzonych dostaw należy przechowywać przez okres odpowiedni dla zasad integracji i ponawiania prób obowiązujących w organizacji.

 

Jak dezaktywować webhook

Dezaktywuj webhook, gdy chcesz tymczasowo zatrzymać dostawy bez usuwania jego konfiguracji.

Webhook można dezaktywować, gdy:

• Aplikacja odbierająca jest poddawana konserwacji.
• Zespół techniczny zastępuje punkt końcowy.
• Połączony przepływ pracy jest tymczasowo wstrzymany.
• Badane są powtarzające się błędy.
• Webhook nie jest obecnie potrzebny.

Po ponownym aktywowaniu webhooka przyszłe pasujące zdarzenia będą mogły zostać dostarczone.

Zdarzenia, które wystąpią, gdy webhook jest nieaktywny, mogą nie zostać automatycznie dostarczone później.

 

Jak usunąć webhook

Usuń webhook, gdy subskrypcja nie jest już potrzebna.

Krok 1: Wybierz Usuń

Znajdź webhook i kliknij działanie Usuń.

Krok 2: Potwierdź usunięcie

Potwierdź, że chcesz trwale usunąć subskrypcję webhooka.

Po usunięciu Enquete przestanie wysyłać nowe dostawy dla tego webhooka.

Historyczne rekordy dostaw mogą pozostać dostępne w rekordach backendu na potrzeby audytów, rozwiązywania problemów lub działań operacyjnych.

Ważne: Jeśli chcesz jedynie tymczasowo wstrzymać webhook, dezaktywuj go zamiast usuwać.

 

Rozwiązywanie problemów ze standardowymi webhookami

Dostawa webhooka kończy się niepowodzeniem lub przekracza limit czasu

Sprawdź następujące elementy:

• Upewnij się, że punkt końcowy jest publicznie dostępny.
• Upewnij się, że punkt końcowy korzysta z protokołu HTTPS.
• Sprawdź, czy zapora sieciowa lub reguła zabezpieczeń nie blokuje żądania.
• Upewnij się, że punkt końcowy akceptuje żądania HTTP POST.
• Upewnij się, że serwer odbierający szybko odpowiada.
• Sprawdź status odpowiedzi i komunikat o błędzie w dziennikach dostaw.
• Upewnij się, że aplikacja odbierająca jest obecnie dostępna.

Długotrwałe zadania powinny być umieszczane w kolejce do przetwarzania w tle zamiast wykonywane w całości przed zwróceniem odpowiedzi przez serwer.

Podpis webhooka jest nieprawidłowy

Poproś zespół techniczny o sprawdzenie, czy:

• Sekret należy do właściwej subskrypcji webhooka.
• Do weryfikacji podpisu używana jest niezmodyfikowana treść żądania.
• Treść JSON nie jest ponownie formatowana przed weryfikacją.
• Oczekiwany format podpisu odpowiada formatowi udokumentowanemu przez Enquete.

Weryfikacja podpisu jest technicznym zadaniem implementacyjnym. Aktualne instrukcje weryfikacji można znaleźć w oficjalnej dokumentacji webhooków.

Nie są odbierane żadne dostawy webhooka

Sprawdź następujące elementy:

• Upewnij się, że webhook jest aktywny.
• Upewnij się, że wybrano właściwą ankietę.
• Upewnij się, że wybrane zdarzenie rzeczywiście wystąpiło.
• Sprawdź, czy adres URL punktu końcowego jest prawidłowy.
• Wyślij dostawę testową.
• Otwórz dzienniki dostaw, aby sprawdzić, czy podjęto próbę wysłania żądania.

Punkt końcowy zwraca odpowiedź 401 lub 403

Odpowiedź 401 lub 403 zwykle oznacza, że serwer odbierający odrzucił żądanie z powodu reguły uwierzytelniania lub autoryzacji.

Sprawdź, czy:

• Punkt końcowy wymaga nieobsługiwanej metody uwierzytelniania.
• Zapora sieciowa lub brama API odrzuca żądanie.
• Punkt końcowy przyjmuje żądania wyłącznie z wybranych sieci.
• Proces weryfikacji podpisu nieprawidłowo odrzuca prawidłowe żądania.

Punkt końcowy zwraca odpowiedź 404

Odpowiedź 404 zwykle oznacza, że adres URL punktu końcowego nie odpowiada żadnej dostępnej trasie na serwerze odbierającym.

Sprawdź pełny adres URL i upewnij się, że trasa istnieje oraz akceptuje żądania HTTP POST.

Punkt końcowy zwraca odpowiedź 500

Odpowiedź 500 oznacza, że w aplikacji odbierającej wystąpił błąd.

Zespół techniczny powinien sprawdzić dzienniki serwera aplikacji odbierającej razem z ładunkiem danych dostawy i identyfikatorem dostawy wyświetlanym w Enquete.

To samo zdarzenie jest przetwarzane więcej niż jeden raz

Żądania webhooka mogą być ponawiane po wystąpieniu błędów lub przekroczeniu limitu czasu.

Zespół techniczny powinien używać wartości X-Enquete-Delivery do identyfikowania dostaw, które zostały już przetworzone.

 

Najlepsze praktyki bezpieczeństwa webhooków

• Zawsze używaj punktu końcowego HTTPS.
• Przed przetworzeniem żądania zweryfikuj podpis webhooka.
• Przechowuj sekret webhooka wyłącznie w bezpiecznych systemach po stronie serwera.
• Nigdy nie ujawniaj sekretu w kodzie frontendu.
• Podczas weryfikacji podpisu używaj niezmodyfikowanej treści żądania.
• Używaj identyfikatora dostawy, aby zapobiegać wielokrotnemu przetwarzaniu.
• Szybko zwracaj odpowiedź oznaczającą powodzenie.
• Długotrwałe operacje przetwarzaj asynchronicznie.
• Monitoruj nieudane dostawy i nietypowo wolne odpowiedzi.
• Po wdrożeniu zmian w punkcie końcowym sprawdzaj dzienniki dostaw.
• Testuj webhook po każdej zmianie konfiguracji.
• Dezaktywuj subskrypcje webhooków, które są tymczasowo nieużywane.
• Usuwaj subskrypcje, które nie są już potrzebne.

 

Lista kontrolna przed aktywowaniem webhooka

Przed użyciem standardowego webhooka w działającym przepływie pracy upewnij się, że wykonano następujące czynności:

1. Utwórz webhook, używając właściwego punktu końcowego HTTPS.
2. Wybierz właściwą ankietę.
3. Wybierz właściwy typ zdarzenia.
4. Skopiuj i bezpiecznie zapisz sekret webhooka.
5. Wdróż weryfikację podpisu na serwerze odbierającym.
6. Wdróż zabezpieczenie przed zduplikowanymi dostawami.
7. Wyślij dostawę testową.
8. Upewnij się, że punkt końcowy zwraca odpowiedź oznaczającą powodzenie.
9. Sprawdź szczegóły żądania i odpowiedzi w dziennikach dostaw.
10. Skonfiguruj monitorowanie i alerty dotyczące błędów dla punktu końcowego odbierającego.
11. Aktywuj webhook dla zdarzeń ankietowych na żywo.

Po uruchomieniu webhooka regularnie sprawdzaj nieudane dostawy i wydajność punktu końcowego, aby upewnić się, że integracja nadal działa prawidłowo.

Informacje dotyczące pól ładunku danych, schematów zdarzeń, przykładów weryfikacji podpisu i innych instrukcji przeznaczonych dla programistów można zawsze znaleźć w oficjalnej dokumentacji webhooków Enquete.