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