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.

Rejestracja hooka przez API:

POST /api/v1/hook

Najważniejsze elementy konfiguracji:

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).

MLS (Message Level Status) to następca starszego MLR i dostarcza stronie wysyłającej informacje zwrotne o odebraniu i przetworzeniu dokumentu. MLS nie jest domyślnie włączony i musi zostać skonfigurowany dla każdej party przez capability reviews w konfiguracji SMP. Po włączeniu MLS PSB obsługuje go automatycznie: jako odbierający Service Provider, PSB wysyła wiadomość MLS z powrotem do nadawcy po odebraniu i dostarczeniu.

Gdy samodzielnie wysyłasz dokumenty przez PSB, otrzymujesz informacje zwrotne MLS od strony odbierającej jako zdarzenie webhook na topicu MessageLevelStatusReceived. Jako odbierający Service Provider, gdy PSB wysyła w Twoim imieniu MLS do wysyłającego SP, następuje odrębny webhook z topikiem MessageLevelStatusSent. Użyj tego topiku, aby monitorować, czy Twoje własne wysyłane odpowiedzi MLS są prawidłowo dostarczane.

PSB 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:

1. Pobrać surowy payload JSON z żądania.
2. Obliczyć hash HMAC SHA256 za pomocą tajnego klucza (tego samego, który podano przy tworzeniu hooka).
3. Porównać obliczony hash z wartością w headerze X-EConnect-Signature.
4. Jeśli się zgadzają, żądanie jest autentyczne.

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:

• IP whitelisting: ograniczenie przychodzących żądań do IP produkcyjnych PSB (104.40.188.59 i 104.47.148.207)
• Uwierzytelnianie OAuth dla webhooków: PSB może uwierzytelniać się w endpoincie za pomocą danych OAuth2
• Mutual SSL: użycie certyfikatów klienta do wzajemnego uwierzytelniania TLS

Gdy skonfigurowanych jest wiele hooków, PSB określa, który hook ma być użyty, na podstawie:

1. Hooki na poziomie PartyId mają pierwszeństwo przed hookami na poziomie environment
2. Specyficzne topiki mają pierwszeństwo przed wildcardami
3. Gdy wiele hooków z filtrami odpowiada temu samemu topikowi: wygrywa najdłuższy filtr (liczony w znakach) -- na przykład filtr z dodatkową klauzulą && wygrywa z krótszym filtrem bez tej klauzuli. Zapobiega to podwójnemu dostarczeniu bez konieczności wzajemnego wykluczania się filtrów.
4. Przy równym priorytecie: hook-id jako kryterium rozstrzygające

Oprócz konkretnych topików można także używać wzorców wildcard, aby przechwytywać wiele typów zdarzeń za pomocą jednego hooka.

Poniżej przedstawiono typowe problemy z webhookami i sposoby ich rozwiązania.

PSB może odebrać fakturę zakupową bez przekazania jej do strony odbierającej. Topic InvoiceReceived oznacza, że PSB odebrał fakturę; bez hooka na tym topicu nic nie trafia do endpointu.

• Brak błędów webhook nie dowodzi, że hook działa. HookSentError istnieje tylko wtedy, gdy skonfigurowany hook nie dostarcza.
• Hook mógł zostać usunięty w międzyczasie. Wcześniejsze udane dostarczenie do tej samej strony/endpointu dowodzi, że hook istniał, a nie że nadal tam jest. Dlatego najpierw sprawdzić aktualną konfigurację hooka, zamiast traktować to jako pierwszą konfigurację.
• Potwierdzenie odbioru po stronie nadawcy to nie to samo co dostarczenie do oprogramowania odbiorcy.

Napraw brakujący hook, aktualizując istniejący hook zamiast go usuwać i tworzyć ponownie.

PSB 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:

• Skonfigurować monitorowanie: subskrybować hook (np. mail-hook) do topicu HookSentError, aby ostateczny błąd dostarczenia był aktywnie sygnalizowany zamiast pozostać niezauważony. Rozważyć również HookSentRetry do wczesnego wykrywania.
• Naprawić przyczynę główną: w przypadku błędu DNS sprawdzić i przywrócić rekord DNS domeny endpointu; w przypadku limitów czasu sprawić, by endpoint odpowiadał szybciej (2xx w ciągu 100 sek., ciężkie przetwarzanie asynchronicznie).
• Odzyskać brakujące zdarzenia: zdarzenia, które nie powiodły się podczas awarii, można pobrać przez endpoint batch. Pięciodniowe okno ponowień oznacza, że terminowe usunięcie usterki w tym okresie może jeszcze uzupełnić zaległości przez regularne dostarczanie.

Pierwsza linia: przerwa po stronie klienta vs. problem techniczny (akceptacja i produkcja)

HookSentError, powtarzający się HTTP 404 lub „endpoint jest offline"/„środowisko akceptacyjne jest wyłączone" może również wynikać z tego, że klient tymczasowo wyłącza endpoint akceptacyjny lub produkcyjny (rozwój, konserwacja). To nie jest incydent platformy eConnect.

1. Potwierdzić objaw: HookSentError, endpoint offline lub HTTP 404 na endpoincie webhook skonfigurowanym przez klienta. Często widoczne jako dokładny tekst Response status code does not indicate success: 404 (Not Found) (zwykle HttpRequestException .NET przy wychodzącym żądaniu hooka). To jest 404 z własnego endpointu klienta (wyłączony lub błędna ścieżka), a nie błąd Peppol PartyId not found przy wysyłce (404 SMP), ani 404 zasobu REST z obsługi błędów API.
2. Zapytać, czy przerwa jest zamierzona i tymczasowa (deweloperzy/klient).
3. Potwierdzone tymczasowe → odnotować, brak dalszych działań po stronie eConnect, dopóki endpoint nie wróci do działania. Gdy endpoint ponownie zwraca 2xx, pominięte zdarzenia można pobrać przez endpoint batch.
4. Niezamierzone lub nieznane → postępować według standardowego runbooka HookSentError powyżej (DNS/SSL/limit czasu, logi, monitorowanie, odzyskiwanie batch).

• Zawsze używać HTTPS dla endpointu webhookowego
• Implementować idempotentne przetwarzanie: PSB może w rzadkich przypadkach dostarczyć zdarzenie więcej niż raz
• Szybko zwracać kod statusu 2xx: PSB traktuje każdą odpowiedź inną niż 2xx jako błąd i ponowi próbę dostarczenia zdarzenia
• Logować wszystkie otrzymane zdarzenia do celów debugowania i audytu
• Używać systemu kolejkowego (queue) po swojej stronie, jeśli przetwarzanie zajmuje czas: najpierw potwierdzić odbiór, potem przetwarzać

Wolą Państwo pobierać dokumenty hurtowo? Batch hook.