Błędy webhooków

Objaw A: Endpoint webhooka zwraca 4xx/5xx

Jak sprawdzić: Panel → Właściwość → Webhooki → Dziennik dostarczania — pokazuje kody statusu i treści odpowiedzi.

Przyczyny i rozwiązania:

Kod statusu	Prawdopodobna przyczyna	Rozwiązanie
401	Weryfikacja podpisu nie powiodła się	Sprawdź kod weryfikacji — zobacz Bezpieczeństwo webhooków
400	Twój endpoint odrzuca format payloadu	Zapisz surową treść i porównaj ze schematem payloadu
404	URL endpointu się zmienił	Zaktualizuj URL webhooka w Właściwość → Webhooki → [Webhook] → Edytuj
500	Błąd w obsłudze webhooka	Sprawdź logi serwera w poszukiwaniu błędu
timeout	Endpoint zbyt długo odpowiada	Odpowiedz natychmiast kodem 200, przetwarzaj asynchronicznie

---

Objaw B: Weryfikacja podpisu webhooka nie powiodła się

Przyczyna: Najczęstsze przyczyny:

1. Nieprawidłowo zbudowany ciąg podpisywania — musi być {timestamp}.{surowa_treść} (nie sparsowany JSON)
2. Używanie innego sekretu niż pokazany w Panelu
3. Odczytywanie buforowanej/zmodyfikowanej treści zamiast surowych bajtów

Rozwiązanie: Upewnij się, że czytasz surową treść żądania przed jakimkolwiek parsowaniem JSON. W Express:

// MUSI używać middleware dla surowej treści
app.use('/webhooks', express.raw({ type: '*/*' }));

---

Objaw C: Dostarczanie webhooków jest opóźnione

Przyczyna: ConsentForge ponawia próby dostarczenia nieudanych z wykładniczym wycofaniem — opóźnienia są oczekiwane po wstępnych awariach.

Rozwiązanie: Napraw podstawowy błąd (patrz Objaw A). Gdy endpoint zwróci 2xx, przyszłe dostarczenia będą natychmiastowe.

---

Objaw D: Brakujące dostarczenia — zdarzenia nie otrzymane

Jak sprawdzić: Porównaj liczbę w dzienniku dostarczania Panelu z liczbą odebraną przez Twój serwer.

Przyczyna: Niektóre zdarzenia mogły wyczerpać wszystkie próby ponowienia (5 prób przez ~2 godziny).

Rozwiązanie: Właściwość → Webhooki → Dziennik dostarczania → Filtruj: Nieudane — użyj przycisku Powtórz, aby ponownie wysłać nieudane dostarczenia.