Webhook nie dochodzi
Jeśli Twój system nie odbiera zdarzeń (np. o zakończonej rozmowie lub wyniku zamówienia), problem prawie zawsze leży po stronie odbierającego endpointu albo jego dostępności. Ta strona pomaga to zdiagnozować. Pełny opis zdarzeń i mechanizmu dostarczania znajdziesz w dokumentacji webhooków.
Najczęstsze przyczyny
| Przyczyna | Objaw | Co zrobić |
|---|---|---|
| Endpoint niedostępny | brak odpowiedzi / przekroczony czas | sprawdź, czy adres działa i odpowiada szybko |
| Błąd serwera (5xx) | zdarzenie odrzucone przez Twój serwer | napraw błąd aplikacji odbierającej |
| Brak HTTPS | zdarzenie nie jest wysyłane | endpoint musi używać https:// |
| Adres prywatny/lokalny | zdarzenie zablokowane | użyj publicznego adresu — adresy prywatne i lokalne są blokowane |
| Zła odpowiedź | ponawianie mimo odbioru | zwracaj kod 2xx od razu po przyjęciu zdarzenia |
Jak diagnozować
Sprawdź adres i protokół
Upewnij się, że endpoint jest publiczny, używa HTTPS i nie wskazuje na adres prywatny ani lokalny (takie adresy są odrzucane ze względów bezpieczeństwa).
Zweryfikuj odpowiedź serwera
Twój serwer powinien odpowiadać kodem 2xx w krótkim limicie czasu. Odpowiedź 5xx lub zbyt wolna sprawia, że dostarczenie liczy się jako nieudane.
Przejrzyj historię dostarczeń
Sprawdź status zdarzeń i kody odpowiedzi w historii dostarczeń, aby ustalić, na którym etapie doręczenie się nie powiodło.
Ponowienia i ponowne wysłanie
Po nieudanym dostarczeniu zdarzenia są ponawiane według harmonogramu z rosnącymi odstępami. Gdy naprawisz endpoint, możesz ponownie wysłać (replay) zdarzenie, żeby nie czekać na kolejną próbę.
Zaprojektuj odbiorcę idempotentnie — to samo zdarzenie może dotrzeć więcej niż raz (przy ponowieniach lub ponownym wysłaniu). Rozpoznawaj zdarzenia po ich identyfikatorze i ignoruj duplikaty, zamiast przetwarzać je ponownie.
Przy zgłoszeniu do wsparcia przygotuj identyfikator zdarzenia i przybliżony znacznik czasu — pozwoli to szybko odszukać konkretne doręczenie.