InnerWeb
Przejdź do treści

Konfiguracja webhooka recepcji krok po kroku

Konfiguracja webhooka recepcji sprowadza się do wpisania adresu odbiorcy w jednym polu panelu i sprawdzenia, że pierwsze zdarzenie dotarło. Cały proces zajmuje administratorowi kilkanaście minut, jeśli odbiorca jest już przygotowany. Poradnik prowadzi przez przygotowanie odbiorcy, ustawienie adresu, test na próbnym gościu i diagnozę typowych problemów.

6
typów zdarzeń do przetestowania
Źródło: karta funkcji
5 s
limit odpowiedzi odbiorcy
Źródło: karta funkcji

Zanim zaczniesz: przygotuj odbiorcę

Pole z adresem w panelu jest ostatnim krokiem, a nie pierwszym. Najpierw odbiorca musi istnieć i przyjmować żądania JSON po HTTPS. Typowym odbiorcą jest workflow w narzędziu n8n, który publikuje wpisy w kanale zakładu na komunikatorze, Mattermost lub Telegram.

Zdarzenia wychodzą z limitem czasu 5 sekund, więc odbiorca powinien odpowiadać szybko, a cięższe przetwarzanie wykonywać po zwróceniu odpowiedzi. Odbiorca, który odpowiada po 8 sekundach, będzie widziany jako niedostępny.

  • Adres odbiorcy dostępny z serwera aplikacji zakładu.
  • Kanał w komunikatorze, w którym mają pojawiać się wpisy.
  • Osoba, która potwierdzi wpis po stronie ochrony.
  • Zgoda działu IT na ruch do adresu odbiorcy.

Krok 1 i 2: wpisz adres w panelu

Administrator otwiera ustawienia integracji w panelu i znajduje pole webhook:reception_url. Wpisuje w nim pełny adres odbiorcy, z protokołem i ścieżką, i zapisuje ustawienie. Puste pole oznacza, że nic nie wychodzi, więc wyczyszczenie adresu jest jednocześnie wyłączeniem integracji.

Zmiana działa dla kolejnych zdarzeń. Zdarzenia, które powstały przed zapisem adresu, nie są wysyłane wstecz, więc nie należy oczekiwać historii w kanale.

Co wpisać, a czego unikać

Wpisz adres docelowy, nie adres przekierowujący. Nie dodawaj w adresie danych uwierzytelniających w postaci jawnej, jeśli odbiorca wspiera osobny sekret. Ustalenia dotyczące zabezpieczenia odbiornika opisujemy w materiale o dobrych praktykach.

Sześć typów zdarzeń według etapu wizyty

Sześć typów zdarzeń według etapu wizytyWykres kołowy: jedno zdarzenie rejestracji, dwa zdarzenia grupy, dwa wyniku szkolenia i jedno wejścia gościa.Rejestracja gościa: 1 zdarzeń (16,7%)Grupa na stanowisku: 2 zdarzeń (33,3%)Wynik szkolenia: 2 zdarzeń (33,3%)Wejście gościa: 1 zdarzeń (16,7%)6zdarzeńRejestracja gościa1 zdarzeń (16,7%)Grupa na stanowisku2 zdarzeń (33,3%)Wynik szkolenia2 zdarzeń (33,3%)Wejście gościa1 zdarzeń (16,7%)
Źródło: Karta funkcji zdarzeń recepcji, podział według etapu wizyty

Krok 3: zarejestruj próbnego gościa

Aby wywołać pierwsze zdarzenie, zarejestruj próbnego gościa na stanowisku lub w panelu. Zdarzenie guest_registered powinno pojawić się w kanale w ciągu kilku sekund. Zdarzenie rejestracji gościa celowo nie niesie numeru telefonu, więc jego brak we wpisie jest oczekiwany.

Wpis powinien zawierać gotowy tekst z systemu oraz czas zdarzenia w strefie Europe/Warsaw w formacie ISO 8601. Jeśli czas wygląda na przesunięty, sprawdź, czy odbiorca nie przelicza go ponownie na własną strefę.

Krok 4 i 5: sprawdź zdarzenia grupy i alert

Webhook publikuje sześć typów zdarzeń, więc test jednego typu nie dowodzi działania pozostałych. Wywołaj także zdarzenie z grupą szkoleniową: grupa na stanowisku rejestracji żyje 34 minuty, a po tym czasie lub po przerwaniu odbiorca dostaje zdarzenie o porażce.

Sprawdź zachowanie wpisów. Wpis o grupie w toku powinien zostać zastąpiony nowym, a przy przerwaniu lub niezaliczeniu pojawić się czerwony wpis z dźwiękiem. Jeśli kanał zapełnia się powtórzeniami, workflow odbiorcy nie zastępuje wpisów i wymaga poprawy.

Sprawdź, że alert nie dubluje się

Alert o niezaliczeniu szkolenia jest chroniony przed duplikatami znacznikiem SET NX w Redisie. Jeśli mimo to widzisz dwa wpisy, sprawdź, czy odbiorca nie przetwarza tego samego żądania dwa razy po stronie własnej usługi.

Krok 6: sprawdź zachowanie przy awarii odbiorcy

Zdarzenia trafiają na kolejkę i są wysyłane asynchronicznie, a błąd webhooka nie przerywa rejestracji gościa, skanu ani zaliczenia szkolenia. Warto to sprawdzić świadomie: wyłącz odbiorcę na chwilę, zarejestruj próbnego gościa i upewnij się, że recepcja działa normalnie.

Po przywróceniu odbiorcy zarejestruj kolejnego gościa i potwierdź, że wpisy wracają. Wynik testu zapisz w protokole odbioru, aby w razie wątpliwości po zmianie konfiguracji można było do niego wrócić.

Typowe problemy i diagnoza

Najczęstsza przyczyna braku wpisu to adres, do którego serwer aplikacji nie ma dostępu w sieci zakładu. Jeśli sieć blokuje ruch wychodzący z hosta aplikacji, rozważ tryb doręczania z odbiorem komunikatów przez poller, opisany w materiale o wyborze trybu direct lub outbox.

Druga przyczyna to odbiorca odpowiadający dłużej niż 5 sekund. Trzecia to pusty lub błędnie zapisany adres w polu webhook:reception_url. Diagnozę zaczynaj od najprostszej: otwórz ustawienie, sprawdź adres i wywołaj próbne zdarzenie.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Gdzie wpisuje się adres webhooka recepcji?

W panelu, w polu webhook:reception_url. Puste pole oznacza, że żadne zdarzenie nie wychodzi.

Czy zdarzenia sprzed zapisu adresu zostaną wysłane?

Nie. Zmiana działa dla zdarzeń powstałych po zapisie, więc historię w kanale buduje się od pierwszej rejestracji po konfiguracji.

Co zrobić, gdy sieć zakładu blokuje ruch wychodzący?

Rozważ tryb outbox, w którym poller odbiera komunikaty kanałem przychodzącym. Szczegóły w materiale o wyborze trybu direct lub outbox.

Skonfigurujmy webhook razem

Na demo pokażemy cały proces od pustego pola do wpisu w kanale komunikatora. Umów rozmowę z zespołem InnerWeb.

Porozmawiajmy