Konfiguracja webhooków w PSB: topiki, zabezpieczenie HMAC SHA256 i IP whitelisting.
Webhooki są podstawową metodą otrzymywania powiadomień w czasie rzeczywistym z PSB. Przy każdym istotnym zdarzeniu, otrzymanej fakturze, zmianie statusu, potwierdzeniu dostarczenia, PSB wysyła żądanie HTTP POST do endpointu z danymi zdarzenia.
Rejestruje się webhook ("hook") w PSB z adresem URL i topikiem. PSB wysyła następnie wszystkie zdarzenia danego topiku na podany URL. Każde zdarzenie zawiera odpowiednie dane jako payload JSON.
Brak interfejsu użytkownika: obecnie nie ma możliwości konfigurowania hooka przez interfejs użytkownika platformy. Hooki konfiguruje się przez API lub przez wsparcie eConnect. Interfejs samoobsługi dla hooków jest w planie rozwoju (planowany na Q4 2026) i będzie częścią Control (Platform 2.0): użytkownicy będą wtedy mogli sami tworzyć, edytować i usuwać hooki. Do tego czasu nie jest planowany artykuł krok po kroku dotyczący ręcznej konfiguracji hooków przez API.
Rejestracja hooka przez API:
POST /api/v1/hook
Najważniejsze elementy konfiguracji:
InvoiceReceived)Uwaga: unikaj szybkiego usuwania i ponownego tworzenia hooków dla tego samego partyId i topiku. Z powodu race conditions w przetwarzaniu zadań może to tymczasowo skutkować brakiem aktywnego hooka, co powoduje niedostarczenie zdarzeń. Po usunięciu hooka poczekaj chwilę przed utworzeniem nowego lub użyj aktualizacji zamiast usunięcia i ponownego utworzenia.
Chcesz dodać dodatkowy topik (np. InvoiceReceived) do istniejącego hooka? Zaktualizuj istniejącą konfigurację webhooka przez standardowe API /hook, tak aby pożądany topik znajdował się w tablicy topics:
{
"topics": ["InvoiceReceived"]
}
Zaktualizuj istniejący hook zamiast go usuwać i ponownie tworzyć. Usuwanie i ponowne tworzenie powoduje race condition, w której zdarzenia mogą tymczasowo nie być dostarczane (patrz ostrzeżenie powyżej).
Brak samoobsługi dla klientów nietech nicznych. Dodanie topiku do istniejącego hooka to zadanie techniczne: osoba wykonująca je musi wiedzieć, dokąd powinien trafić webhook (URL endpointu) i rozumieć, czym jest webhook. Klient nietech niczny zazwyczaj nie może zrobić tego samodzielnie. Zaangażuj osoby z wiedzą techniczną (dział IT klienta lub wsparcie eConnect).
InvoiceReceivedInvoiceSentInvoiceSentErrorInvoiceSentRetryInvoiceResponseReceivedOrderReceivedPSB zabezpiecza wszystkie dostarczenia webhooków za pomocą podpisów HMAC SHA256. Przy każdym żądaniu PSB wysyła header:
X-EConnect-Signature: sha256={handtekening}
Aby zweryfikować podpis:
X-EConnect-Signature.Należy również sprawdzać pole sentOn w payloadzie. Jeśli ten znacznik czasu jest starszy niż 5 minut, żądanie należy odrzucić. Zapobiega to atakom replay, w których przechwycone żądanie jest odtwarzane później.
Oprócz weryfikacji HMAC, PSB oferuje dodatkowe warstwy bezpieczeństwa:
104.40.188.59 i 104.47.148.207)Gdy skonfigurowanych jest wiele hooków, PSB określa, który hook ma być użyty, na podstawie:
&& wygrywa z krótszym filtrem bez tej klauzuli. Zapobiega to podwójnemu dostarczeniu bez konieczności wzajemnego wykluczania się filtrów.Poniżej przedstawiono typowe problemy z webhookami i sposoby ich rozwiązania.
sha256=sentOn starsze niż 5 minutHookSentError (patrz niżej); pobrać brakujące zdarzenia przez endpoint batchX-EConnect-Delivery (unikalne UUID) do deduplikacjiPSB wysyła zdarzenia webhook (np. InvoiceReceived po otrzymaniu e-faktury) do skonfigurowanego endpointu. Jeśli ten endpoint jest niedostępny — z powodu limitu czasu, błędu SSL lub błędu DNS jak No such host is known — PSB ponawia próby z wykładniczym wycofaniem przez 5 dni (limit czasu 100 sek. na próbę). Każda próba generuje zdarzenie HookSentRetry; po 5 dniach bez odpowiedzi 2xx emitowany jest HookSentError jako status końcowy i PSB kończy ponowne próby.
Konsekwencja: otrzymana e-faktura nie zostanie dostarczona do klienta, dopóki endpoint jest niedostępny, bez wiedzy klienta. Zalecane działania:
HookSentError, aby ostateczny błąd dostarczenia był aktywnie sygnalizowany zamiast pozostać niezauważony. Rozważyć również HookSentRetry do wczesnego wykrywania.Należy wziąć surowe ciało JSON żądania, obliczyć hash HMAC SHA256 przy użyciu sekretu podanego podczas tworzenia hooka i porównać go z wartością w nagłówku X-EConnect-Signature (po prefiksie sha256=). Jeśli wartości się zgadzają, oznacza to, że żądanie pochodzi z PSB i nie zostało zmodyfikowane w trakcie przesyłania.
Należy sprawdzić, czy sentOn nie jest starszy niż 5 minut. Jeśli znacznik czasu jest zbyt stary, żądanie należy odrzucić. Zapobiega to atakom typu replay, w których wcześniej przechwycone żądanie jest ponownie przesyłane, nawet jeśli podpis jest technicznie poprawny.
Należy zaimplementować idempotentne przetwarzanie po swojej stronie, ponieważ PSB może w rzadkich przypadkach dostarczyć zdarzenie więcej niż raz. Ponadto należy szybko zwrócić kod statusu HTTP 2xx: każda inna odpowiedź jest traktowana jako błąd i powoduje ponowienie. W przypadku złożonego przetwarzania warto najpierw potwierdzić odbiór, a następnie przetworzyć dane za pomocą kolejki.
Wolą Państwo pobierać dokumenty hurtowo? Batch hook.
Zobacz endpointy webhooków