szablon dokumentacji webhooka (dla nadawcy i odbiorcy)

Szablon dokumentacji webhooka opisuje format powiadomień zarówno dla nadawcy, jak i odbiorcy integracji.

Zakres i układ szablonu dokumentacji webhooka

Szablon dokumentacji webhooka powinien opisywać cały kontrakt komunikacyjny między systemem wysyłającym zdarzenie a systemem odbierającym powiadomienie. Webhook nie jest osobnym protokołem transportowym, lecz sposobem przekazywania informacji, najczęściej przez żądanie HTTP wysłane automatycznie po wystąpieniu określonego zdarzenia. Dokument należy rozpocząć od wskazania nazwy zdarzenia, warunków jego wygenerowania, adresu docelowego oraz wersji kontraktu. Warto rozdzielić informacje dotyczące środowiska testowego i produkcyjnego, ponieważ mogą używać różnych adresów URL, kluczy uwierzytelniających lub reguł filtrowania.

Opis powinien zawierać metodę HTTP, zwykle POST, wymagane nagłówki, format treści, kodowanie znaków oraz strukturę danych. Jeśli ładunek jest zapisany w JSON, należy wskazać typ application/json i opisać pola wraz z ich typami, znaczeniem, obowiązkowością oraz przykładowymi wartościami. JSON jest formatem opisanym w RFC 8259, ale sam webhook może stosować dodatkowe reguły, na przykład ograniczenie do płaskich obiektów, numerów identyfikacyjnych zapisanych jako tekst lub dat przedstawianych w formacie ISO 8601.

Informacje wymagane po stronie nadawcy

Dokumentacja dla nadawcy powinna określać, kiedy system tworzy powiadomienie i jakie dane umieszcza w żądaniu. Trzeba jednoznacznie opisać nazwę zdarzenia, identyfikator dostawy, czas utworzenia komunikatu oraz identyfikator obiektu, którego dotyczy zdarzenie. Przydatny jest również numer wersji schematu, ponieważ pozwala odbiorcy rozpoznać zmianę formatu bez zgadywania na podstawie zawartości żądania. Jeżeli jedno zdarzenie może zostać wysłane do wielu adresów, identyfikator dostawy powinien być unikalny przynajmniej w zakresie danego nadawcy.

Nadawca powinien opisać sposób ustalania, czy dostawa zakończyła się powodzeniem. Typowo odpowiedź z zakresem 2xx oznacza przyjęcie żądania przez odbiorcę, natomiast odpowiedzi 4xx i 5xx wymagają osobnego traktowania. Błąd 4xx może wskazywać na nieprawidłowy format, brak autoryzacji lub niedostępny zasób i nie zawsze powinien powodować ponawianie. Błąd 5xx, zerwane połączenie albo przekroczenie limitu czasu częściej oznaczają problem przejściowy. Szablon powinien podawać czas oczekiwania, liczbę prób, odstępy między próbami oraz sposób rejestrowania nieudanych dostaw.

Jeżeli nadawca ponawia dostarczenie tego samego zdarzenia, dokumentacja musi ostrzegać o możliwości duplikatów. Odbiorca powinien otrzymać stabilny identyfikator dostawy, a nadawca powinien opisać, czy ponowienie zachowuje identyczny ładunek i identyfikator. Takie informacje są potrzebne do zastosowania idempotencji, czyli przetworzenia tej samej dostawy więcej niż raz bez wielokrotnego wykonania skutku biznesowego.

Kontrakt odbiorcy: walidacja, bezpieczeństwo i odpowiedź

Po stronie odbiorcy szablon powinien wskazywać wymagania dotyczące publicznie dostępnego adresu HTTPS, obsługiwanej metody oraz dopuszczalnych nagłówków. HTTPS szyfruje transmisję przy użyciu TLS, ale nie potwierdza samodzielnie, że żądanie pochodzi od właściwego nadawcy. Dlatego dokumentacja powinna opisać mechanizm uwierzytelniania, na przykład token przekazywany w nagłówku albo podpis wiadomości obliczany z użyciem współdzielonego sekretu. Przy podpisie HMAC odbiorca musi znać używany algorytm, sposób łączenia danych wejściowych, kodowanie wyniku oraz nagłówek zawierający podpis.

Bezpieczny schemat podpisu często obejmuje znacznik czasu i surowe bajty odebranego ciała. Odbiorca powinien najpierw odczytać niezmienioną treść żądania, sprawdzić podpis i odrzucić komunikat poza dopuszczalnym oknem czasowym, a dopiero potem analizować JSON. Nie wolno obliczać podpisu na ponownie sformatowanym obiekcie, ponieważ zmiana białych znaków lub kolejności elementów może zmienić dane wejściowe. Dokument powinien także określać maksymalny rozmiar ładunku, dopuszczalne typy zdarzeń, zachowanie przy nieznanych polach i wymagany sposób ochrony sekretu.

Odbiorca powinien szybko potwierdzić przyjęcie poprawnego żądania, a dłuższe operacje wykonywać później, jeśli architektura systemu na to pozwala. W dokumentacji należy podać oczekiwany kod odpowiedzi, format ewentualnego komunikatu błędu oraz sytuacje, w których dostawa jest odrzucana. Warto opisać również testowy endpoint, przykładowe żądanie, przykładową odpowiedź i przypadki graniczne: brak pola obowiązkowego, nieprawidłowy typ danych, powtórzony identyfikator dostawy, stary znacznik czasu oraz nieznany typ zdarzenia.

Wykorzystanie dokumentacji przy sprawdzaniu aplikacji na komputerze

Szablon jest użyteczny podczas diagnozowania aplikacji klienckiej, która ma odbierać powiadomienia pośrednio przez lokalny komponent, usługę synchronizującą albo panel internetowy. Na laptopie lub komputerze PC można porównać adres skonfigurowanego endpointu z adresem opisanym dla właściwego środowiska, sprawdzić obecność nagłówka Content-Type, zweryfikować kod odpowiedzi oraz ustalić, czy problem występuje przed wysłaniem, w czasie transmisji, czy dopiero podczas parsowania danych. Sam fakt, że nadawca odnotował próbę wysyłki, nie dowodzi jeszcze, że aplikacja użytkownika poprawnie przetworzyła zdarzenie.

Praktyczna kontrola obejmuje sprawdzenie zegara systemowego, certyfikatu TLS, rozwiązywania nazwy DNS, reguł zapory sieciowej oraz logów obu stron. Rozbieżność między dokumentacją a implementacją może polegać na zmianie nazwy pola, innym kodowaniu daty, pominięciu identyfikatora dostawy albo błędnym założeniu, że kolejność zdarzeń jest zawsze zachowana. Dokument powinien jasno wskazywać, czy kolejność jest gwarantowana, czy odbiorca musi sortować zdarzenia według czasu lub numeru sekwencyjnego. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i podzespołów, więc przy problemach lokalnego stanowiska można oddzielić usterkę sprzętu lub systemu od błędu konfiguracji samego webhooka.

Kompletny szablon powinien kończyć się historią zmian kontraktu i procedurą zgłaszania problemów technicznych. Każda zmiana pola, sposobu podpisywania, kodów odpowiedzi, limitów czasu lub zasad ponawiania powinna mieć numer wersji i datę obowiązywania. Dzięki temu nadawca i odbiorca mogą ustalić, z jaką wersją komunikatu pracuje dana instalacja, odtworzyć konkretną dostawę na podstawie jej identyfikatora oraz rozdzielić błąd transportu HTTP od błędu logiki przetwarzania danych.