Webhook, który „nie działa", to w Bitrix24 (Alaio) dwie zupełnie różne awarie ukryte pod jednym słowem, a lekarstwo na jedną nie pomaga drugiej: albo zdarzenie wychodzące nigdy nie dociera do twojego handlera, albo wywołanie przychodzące zwraca błąd zamiast danych. Martwa synchronizacja, bot, który przestał pisać, system księgowy bez wczorajszych deali — każdy z tych objawów to jeden z dwóch przypadków w przebraniu. Najpierw ustal który, potem przejdź sprawdzenia po kolei.

Wychodzący czy przychodzący: która połowa jest zepsuta?

Webhook przychodzący to adres URL z kluczem, którym twoja usługa woła portal; wychodzący działa odwrotnie — to portal woła ciebie, gdy zajdzie zdarzenie. Jeśli w logach widać wysłane żądanie i wracający komunikat błędu, problem jest po stronie przychodzącej, a błąd sam nazywa przyczynę. Jeśli w logach nie ma nic, problem jest po stronie wychodzącej — i nigdzie nie ma błędu, co właśnie czyni diagnozę tak żmudną. Jak tworzy się oba typy, opisuje przewodnik po webhookach; ta strona jest o tym, co robić, gdy milczą.

Dlaczego webhook wychodzący nigdy nie dociera do handlera?

Zdarzenia nie lecą z portalu wprost pod twój adres. Trafiają do kolejki na osobnym serwerze dostarczania i dopiero on wysyła POST. Trzy cechy tego serwera tłumaczą większość ciszy. Handler musi być osiągalny z publicznego internetu: adres na localhost albo w sieci prywatnej nie dostanie nic, a firewall przepuszczający wyłącznie znanych partnerów działa tak samo. Handler musi odpowiadać szybko: kolejka mierzy czas odpowiedzi i woła wolne handlery rzadziej, wydłużając odstęp między próbami — ciężki handler staje się zawodny, ani razu nie padając otwarcie. A ładunek jest celowo ubogi, w zasadzie identyfikator obiektu i nazwa zdarzenia, więc kod czekający na gotowe wartości pól odczytuje pustą strukturę. Po pola sięgnij osobnym wywołaniem REST.

Czy to na pewno zdarzenie, które subskrybowałeś?

Druga najczęstsza przyczyna to sprawna subskrypcja niewłaściwego zdarzenia. Zdarzenia aktualizacji uruchamiają się przy każdej zmianie obiektu, także tej wprowadzonej przez twoją własną automatyzację — wygląda to jak zdublowane dostawy, a czasem zapętla się. Handlery zarejestrowane w sekcji zasobów dla programistów i handlery zarejestrowane przez aplikację metodą event.bind leżą w różnych listach: subskrypcja, na którą patrzysz, nie musi być tą działającą — a powiązania aplikacji znikają, gdy zostanie ona usunięta lub zaktualizowana. Sprawdzenie kosztuje minutę: wykonaj akcję ręcznie i zobacz w logu dostępu, czy przyszedł POST.

Handler był wyłączony — czy odzyskam zdarzenie?

Nie, i to jest właśnie ta cecha, którą pomija większość projektów integracji. Jeśli twój serwer nie odpowie albo zwróci błąd, serwer kolejki zapisze niepowodzenie i nie wyśle zdarzenia ponownie. Nie ma ponowień ani kolejki nieodebranych: dziesięć sekund wdrożenia kosztuje po cichu wszystkie zdarzenia z tego okna.

Rozwiązania są dwa. Dla kierunku przychodzącego podepnij subskrypcję jako zdarzenie offline — portal trzyma zdarzenia w kolejce, którą twoja usługa odbiera we własnym tempie metodą event.offline.get, więc przestój opóźnia dostawę, zamiast ją niszczyć. Dla wywołań, które zaczynają się w portalu, wysyłaj je z procesu: Niezawodny webhook ponawia nieudane próby w zadanym odstępie, pozwala określić, które kody odpowiedzi liczą się jako sukces, raportuje liczbę prób i powiadamia wybranych pracowników, jeśli dostawa ostatecznie się nie uda.

Dlaczego webhook przychodzący zwraca błąd?

Tu dostajesz kod — czytaj jego, a nie zdanie obok. Błąd uprawnień oznacza, że klucz utworzono bez zakresu, którego wymaga metoda, a zakresy ustala się przy tworzeniu: klucz trzeba wystawić na nowo. Błąd dostępu zwykle znaczy, że klucz jest w porządku, ale jego właściciel nie: webhook działa z prawami pracownika, który go utworzył, więc zwolniony właściciel albo taki, który nie widzi lejka, kończy odmową przy w pełni ważnym tokenie. QUERY_LIMIT_EXCEEDED to limit częstotliwości, a nie zepsuty klucz: operacje masowe pakuje się w wywołania batch i ponawia z rosnącym opóźnieniem. Wywołanie zwykłym HTTP zamiast HTTPS jest odrzucane od razu.

Jak przetestować webhook, a nie zgadywać?

Loguj surowe ciało żądania przed parsowaniem: połowa przypadków „webhook się zepsuł" to handler, który POST dostał i wywrócił się na własnym parsowaniu. Sprawdzaj też nadawcę — wraz z wywołaniem zdarzenia przychodzi token aplikacji, a porównanie go z zapisaną wartością jest zarazem zabezpieczeniem i szybką odpowiedzią na pytanie, czy ten POST w ogóle przyszedł z portalu.

Kierunek przeciwny przetestujesz z wnętrza portalu: wstaw do procesu Żądanie HTTP GET/POST — wyśle zapytanie pod twój adres i zwróci treść odpowiedzi, kod statusu oraz znacznik Y/N, czyli pokaże, czy twój endpoint w ogóle odpowiada sieci portalu; Wyciągnij wartość z JSON po ścieżce wyjmie jedno pole do czytelnego wpisu w logu. Jeśli proces, który miał wysłać żądanie, w ogóle nie wystartował, trop prowadzi do reguł automatyzacji, które nie działają.

Co dalej

Cisza znaczy wychodzący, komunikat błędu znaczy przychodzący: sam ten podział oszczędza większość czasu. Potem projektuj zgodnie z ograniczeniem, a nie wbrew niemu — zdarzenia nigdy nie są wysyłane ponownie, więc wszystko, czego nie wolno zgubić, idzie przychodząco przez subskrypcję offline i wychodząco przez niezawodny webhook, a oba to zwykłe klocki reguł automatyzacji w Bitrix24. Pozostałe znajdziesz w katalogu Roboteka; brakuje potrzebnego — opisz zadanie, zbudujemy go za darmo i dodamy do wspólnej biblioteki.