Czym jest webhook
Webhook to automatyczne powiadomienie HTTP. Gdy w systemie zachodzi zdarzenie (np. powstaje nowy rachunek albo zmienia się produkt), GoPOS wysyła żądanie na wskazany przez Ciebie adres URL. Odbiorca dostaje dane w momencie zdarzenia, zamiast cyklicznie pytać API, czy coś się zmieniło.
Webhooki są dostępne w GoPOS, GoCRM, GoOrder i GoStock.
Gdzie znajdziesz webhooki
Webhooki konfiguruje się w kontekście konkretnej lokalizacji. W panelu kliknij swoją nazwę użytkownika (lewy dolny róg) i wybierz Logi → Webhooki.
Na liście widzisz nazwę, zasób i adres URL każdego webhooka. Kolorowa kropka przy nazwie pokazuje stan: zielona oznacza webhook aktywny, czerwona — zablokowany.
Zasób i wysyłane zdarzenia
Nowy webhook dodajesz przyciskiem Dodaj. Do wypełnienia są cztery pola:
Nazwa — dowolna, ułatwia późniejsze odnalezienie webhooka na liście.
URL — adres, na który mają trafiać żądania.
Zasób — obszar danych, którego dotyczy subskrypcja (np. Zamówienie, Koszt zamówienia, Status przygotowania zamówienia, Dostępność, Kategoria, Produkt, Wariant, Grupa klientów, Klient).
Wysyłane zdarzenia — opcjonalne zawężenie subskrypcji do wybranych typów zdarzeń.
Pole Wysyłane zdarzenia warto wykorzystać. Zamiast odbierać wszystkie zmiany danego zasobu, możesz wskazać tylko te typy, które faktycznie obsługujesz — na przykład samo utworzenie rachunku, bez aktualizacji i usunięcia. Jeśli nie wybierzesz nic, webhook otrzyma wszystkie zdarzenia zasobu, tak jak dotychczas.
Efekt zawężenia jest podwójny: mniej ruchu po obu stronach i mniej filtrowania po stronie odbiorcy. W podglądzie webhooka pole Wysyłane zdarzenia pokazuje aktualny wybór albo wartość „Wszystkie”.
Co się dzieje, gdy wysyłka się nie uda: ponowienia
Odpowiedź z kodem 2xx kończy wysyłkę — żądanie uznajemy za dostarczone. Błąd serwera, timeout lub brak połączenia uruchamiają ponowienie. Kolejnych prób jest maksymalnie 7, a odstępy między nimi rosną, więc cały cykl rozkłada się na ponad 10 godzin:
Ponowienie | Odstęp od poprzedniej próby | Czas od zdarzenia |
1 | 5 sekund | ~5 s |
2 | 20 sekund | ~25 s |
3 | 1 minuta | ~1,5 min |
4 | 5 minut | ~6,5 min |
5 | 30 minut | ~36 min |
6 | 2 godziny | ~2,6 h |
7 | 8 godzin | ~10,5 h |
Dzięki temu krótka awaria po stronie odbiorcy zwykle nie powoduje utraty zdarzenia — jedna z kolejnych prób trafia już na działający serwis.
Ponieważ to samo zdarzenie może dotrzeć więcej niż raz (np. gdy odpowiedź 2xx nie dojdzie do nas z powodu timeoutu), odbiorca powinien rozpoznawać duplikaty po identyfikatorze zdarzenia.
Podgląd i ręczne ponowienie
Wszystkie żądania znajdziesz w Logi → Żądania. Na liście widoczne są data utworzenia, data planowanego wysłania, typ (WEBHOOK), status oraz kontekst zdarzenia — na przykład ITEM_GROUP_UPDATED/ITEM_GROUP/291.
Kolumna Data planowanego wysłania pokazuje, kiedy nastąpi kolejna próba, a status informuje o etapie: Otwarty to żądanie oczekujące, Zakończony — dostarczone, Błąd — nieudane.
Jeśli chcesz wysłać żądanie od razu, bez czekania na harmonogram, wejdź w jego podgląd i wybierz Więcej → Wyślij ponownie.
Blokada wysyłki webhooka
Gdy próby dostarczenia nadal się nie udają, webhook zostaje zablokowany automatycznie. Dzieje się to w dwóch trybach:
Natychmiast, gdy odpowiedź jednoznacznie wskazuje błąd konfiguracji: 400, 401, 403, 404, 422. Ponawianie nie ma tu sensu — zły adres czy brak autoryzacji nie naprawią się same.
Po serii kolejnych nieudanych prób, gdy błędy mogą być przejściowe: 500, 429, timeouty, nieosiągalna domena.
W drugim przypadku pula wynosi 25 błędów pod rząd. Jeśli w ciągu 25 kolejnych prób wysyłki zdarzeń nie uda się ani jedna, webhook zostaje zablokowany. Powód wyłączenia zapisujemy w formie, która to pokazuje — na przykład HTTP 503 x25.
Zablokowany webhook przestaje generować nowe wysyłki, a te, które są już w kolejce, nie są dalej ponawiane.
Pojedyncze incydenty nie blokują działającego webhooka — pierwsza udana wysyłka zeruje licznik błędów i pula 25 liczy się od nowa.
Diagnostyka w podglądzie webhooka
Przy każdym webhooku zapisujemy datę i powód blokady, więc od razu widać, co się stało. W podglądzie znajdziesz:
Data wyłączenia i Powód wyłączenia,
Liczba kolejnych nieudanych prób,
Ostatnia nieudana próba,
listę żądań ze statusami i podglądem każdego z nich.
To zwykle wystarcza, żeby odróżnić literówkę w adresie od awarii serwisu odbierającego.
Po awarii pamiętaj o odblokowaniu
Zablokowany webhook nie odblokuje się sam. Jeśli serwis odbierający webhooki miał awarię i z tego powodu webhook został zablokowany, naprawienie problemu po stronie odbiorcy nie przywraca wysyłki. Do momentu przywrócenia zdarzenia nie są do niego wysyłane.
Aby przywrócić webhook, wejdź w jego podgląd i wybierz Więcej → Przywróć. To jedna akcja — licznik błędów jest wtedy zerowany, a webhook wraca do normalnej pracy.
Warto uwzględnić ten krok w procedurze powrotu po awarii: po przywróceniu usługi odbierającej sprawdź, które pozycje webhooków mają czerwoną kropkę, i przywróć je.
Potrzebujesz pomocy?
Sprawdź nasz dział FAQ, aby znaleźć szybkie odpowiedzi. W razie dalszych pytań skontaktuj się z naszą obsługą klienta poprzez CHAT dostępny w aplikacji.