InnerWeb
Przejdź do treści

Checklista odbioru integracji webhook i API w zakładzie

Odbiór integracji opartej na webhookach i API warto oprzeć na jednej liście kontrolnej, którą integrator i kierownik IT odhaczają razem na etapie pilotażu. Poniżej zebraliśmy dwanaście punktów: tryb doręczania, ograniczenia outboxu, potwierdzenia dostaw, token maszynowy i kody odpowiedzi. Każdy punkt ma komentarz, po czym poznać, że jest spełniony.

89
wpisów w jednej paczce pollera
Źródło: karta funkcji
300 s
czas rezerwacji wpisu przed zwrotem do puli
Źródło: karta funkcji

Dlaczego odbiór integracji wymaga listy

Integracja webhookowa działa na styku dwóch systemów i dwóch zespołów, więc łatwo o sytuację, w której każdy zakłada, że drugi sprawdził krytyczny element. Lista kontrolna wymusza, że każdy punkt ma właściciela i dowód.

Na etapie pilotażu koszt błędu jest najniższy: ruch jest mały, a zespół uważnie obserwuje wyniki. Odbiór integracji po pilotażu pozwala przejść do wdrożenia z wiedzą, które ograniczenia są akceptowalne, a które wymagają rozwiązania.

Tryb doręczania i jego ograniczenia

Pierwsza decyzja dotyczy trybu doręczania. Ustawienie webhook:delivery_mode ma dwie wartości: direct, domyślną, i outbox. Każda inna wartość niż outbox oznacza direct, więc literówka w ustawieniu po cichu włącza tryb bezpośredni. Sprawdź wartość w panelu i zapisz ją w protokole.

Tryb outbox zapisuje treść webhooka w tabeli, a zewnętrzny poller odbiera wpisy i wysyła je dalej tym samym ładunkiem. Powstał dla instalacji, w których sieć blokuje ruch wychodzący z hosta aplikacji. Ma jednak ograniczenia, które odbiór musi uwzględnić.

Ograniczenia, które trzeba zaakceptować lub obejść

Outbox nie ma limitu prób, odstępu między ponowieniami ani alertu o wpisach utkniętych. Brakuje też zadania czyszczącego tabelę, więc zakończone wpisy rosną bez końca. Nieudane potwierdzenie failed cofa wpis do stanu pending i zwiększa licznik prób, więc poller ponawia go bez końca.

Odbiór powinien dokumentować, kto po stronie zakładu monitoruje wpisy utknięte i jak rośnie tabela. To nie jest wada do ukrycia, tylko znane ograniczenie, które organizacja obejmuje procedurą.

Parametry odbioru outboxu

Parametry odbioru outboxuWykres: paczka pollera 89 wpisów, rezerwacja 300 sekund, 6 typów zdarzeń recepcji.0100200300liczbaWpisów w paczce: 89 liczba89 liczbaWpisów w paczceSekundy rezerwacji: 300 liczba300 liczbaSekundy rezerwacjiTypy zdarzeń recepcji: 6 liczba6 liczbaTypy zdarzeń recepcji
Źródło: Karty funkcji webhook outbox i zdarzeń recepcji

Potwierdzenia i ponowienia

Pobranie oczekujących wpisów atomowo rezerwuje paczkę do 89 wpisów pod blokadą zapisu w transakcji, więc dwa pollery nie odbiorą tego samego wpisu. Wpis w stanie delivering, którego rezerwacja trwa dłużej niż 300 sekund, wraca do puli i może zostać odebrany ponownie.

Potwierdzenie dostawy przyjmuje status delivered lub failed z opcjonalnym opisem błędu i jest idempotentne: potwierdzenie wpisu już doręczonego nic nie zmienia. Odbiór powinien obejmować test, w którym poller wysyła to samo potwierdzenie dwa razy i nic się nie zmienia.

API i token maszynowy

Wywołania API wymagają tokenu maszynowego. Odbiór sprawdza, że token jest przechowywany po stronie serwera, nie w kodzie przeglądarki, i że zły lub brakujący token daje odpowiedź 401. Dla wniosków o dostęp odpowiedź 201 oznacza nowy wniosek, 200 powtórkę tego samego identyfikatora żądania, a 400 błędne dane.

Warto sprawdzić również, że powtórzone wywołanie z tym samym identyfikatorem nie tworzy duplikatu. To najczęstsza usterka integracji, które działają w teście jednym wywołaniem, a w produkcji powtarzają je przy braku odpowiedzi.

Jak prowadzić odbiór

Odbiór prowadzi się w jednej sesji z integratorem i kierownikiem IT. Każdy punkt listy kończy się dowodem: zrzutem ustawienia, wpisem w kanale albo odpowiedzią z kodem. Brak dowodu oznacza punkt niespełniony.

Punkty niespełnione trafiają do krótkiej listy poprawek z terminem, a odbiór uznaje się za zakończony po ich zamknięciu. Lista wraz z dowodami wchodzi do dokumentacji integracji i służy przy audycie.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Kiedy przeprowadzać odbiór integracji?

Na końcu pilotażu, gdy ruch jest rzeczywisty, a zespół ma jeszcze czas na poprawki bez presji produkcyjnej.

Czy outbox gwarantuje, że wpis nie zginie?

Wpis jest zapisany w tabeli do czasu potwierdzenia, ale nie ma limitu prób ani alertu o wpisach utkniętych. Dlatego odbiór wymaga procedury monitoringu.

Czy potwierdzenie można wysłać wielokrotnie?

Tak. Potwierdzenie wpisu już doręczonego jest idempotentne i niczego nie zmienia.

Przeprowadź odbiór z naszym zespołem

Przygotujemy dla integratora i działu IT protokół odbioru oparty na tej liście. Umów rozmowę z InnerWeb.

Porozmawiajmy