Co powinien zwracać endpoint webhooka śledzenia? Kody statusu, limity czasu i ponowienia?
Endpoint webhooka śledzenia powinien zwracać szybką, zamierzoną odpowiedź 2xx po zaakceptowaniu zdarzenia do przetwarzania. W większości integracji najbezpieczniejszy schemat obejmuje uwierzytelnienie żądania, weryfikację danych, zapisanie lub umieszczenie zdarzenia w kolejce oraz potwierdzenie go za pomocą 200 OK lub 202 Accepted. Używaj odpowiedzi 4xx w przypadku żądań, których nadawca nie powinien ponawiać, oraz odpowiedzi 5xx, gdy tymczasowy problem po stronie serwera uniemożliwił akceptację. Dokładne działanie limitu czasu i ponawiania nadal zależy od umowy dostawcy webhooka, dlatego implementację należy projektować w oparciu o udokumentowane zachowanie nadawcy, a nie założenia.
W przypadku webhooka dotyczącego śledzenia lub statusu przesyłki to rozróżnienie ma znaczenie, ponieważ zdarzenia dostawy mogą nadejść więcej niż raz, w niewłaściwej kolejności lub zostać odtworzone po awarii sieci. Zadaniem endpointu nie musi być ukończenie każdej operacji biznesowej przed udzieleniem odpowiedzi. Jego pierwszym zadaniem jest wiarygodne podjęcie decyzji, czy zdarzenie zostało zaakceptowane.
Umowa dotycząca odpowiedzi w praktyce
Odpowiedź webhooka ma dwóch odbiorców: system wysyłający oraz własną aplikację. Nadawca potrzebuje jasnego wyniku HTTP, aby zdecydować, czy oznaczyć dostarczenie jako udane, ponowić próbę czy ją zakończyć. Aplikacja potrzebuje wystarczającej ilości czasu na zweryfikowanie i trwałe zapisanie zdarzenia. Łatwiej osiągnąć te cele, gdy endpoint ma krótką ścieżkę synchroniczną i oddzielną ścieżkę przetwarzania asynchronicznego.
- Odbierz żądanie HTTP przez HTTPS.
- Sprawdź podpis, dane uwierzytelniające, znacznik czasu lub inne mechanizmy kontroli integralności żądania wymagane przez dostawcę.
- Przeanalizuj i zweryfikuj dane bez wykonywania powolnych operacji zależnych od innych systemów.
- Zapisz zdarzenie lub rekord deduplikacji i odwołanie do zdarzenia w trwałym magazynie albo niezawodnej kolejce.
- Zwróć zamierzoną odpowiedź 2xx.
- Przetwarzaj aktualizację śledzenia, powiadomienie klienta, zmianę stanu zapasów lub inne działanie biznesowe asynchronicznie.
Odpowiedź nie powinna oznajmiać akceptacji, jeśli zdarzenie istnieje wyłącznie w pamięci procesu. Jeśli aplikacja ulegnie awarii natychmiast po zwróceniu powodzenia, zdarzenie, które nigdy nie zostało zapisane, może zostać utracone, podczas gdy nadawca będzie uważał dostarczenie za udane. Punkt, w którym zwracasz 2xx, powinien zatem odpowiadać rzeczywistej gwarancji trwałości danych.
Jaki kod statusu powinien zwracać webhook?
| Odpowiedź | Znaczenie dla nadawcy | Typowe zastosowanie webhooka |
|---|---|---|
200 OK | Żądanie zostało zaakceptowane i pomyślnie obsłużone. | Praktyślna wartość domyślna po weryfikacji i trwałej akceptacji. |
202 Accepted | Żądanie zostało zaakceptowane do przetwarzania, ale prace mogą być kontynuowane. | Przydatne, gdy zdarzenie zostało bezpiecznie umieszczone w kolejce, lecz przetwarzanie biznesowe odbywa się asynchronicznie. |
204 No Content | Żądanie zakończyło się powodzeniem i treść odpowiedzi nie jest potrzebna. | Odpowiednie, gdy dostawca akceptuje pustą odpowiedź powodzenia. |
400–499 | Żądanie jest nieprawidłowe, nieuwierzytelnione lub nieakceptowalne w przesłanej postaci. | Niepoprawne dane, nieudane uwierzytelnienie, nieprawidłowy podpis lub trwale odrzucone zdarzenie. |
429 Too Many Requests | Odbiorca stosuje ograniczenie szybkości żądań. | Używaj wyłącznie wtedy, gdy sposób ponawiania przez nadawcę jest zgodny z zasadami ograniczania szybkości. |
500–599 | Odbiorca nie mógł zaakceptować żądania z powodu problemu po stronie serwera lub problemu tymczasowego. | Awaria bazy danych, kolejki lub zależności albo nieoczekiwany błąd aplikacji. |
200 OK jest często wyborem najmniej zaskakującym, ponieważ jest powszechnie rozumiany jako pomyślne odebranie. 202 Accepted jest również semantycznie przydatny, gdy endpoint zaakceptował zdarzenie do późniejszego przetwarzania. Żaden z tych kodów nie jest automatycznie właściwy: dokumentacja nadawcy może określać, które odpowiedzi 2xx są uznawane za udane, a niektórzy dostawcy mogą wymagać konkretnej treści lub typu zawartości.
Nie zwracaj odpowiedzi 2xx wyłącznie dlatego, że żądanie HTTP dotarło do serwera. Jeśli weryfikacja podpisu nie powiedzie się lub danych nie można bezpiecznie zinterpretować, odpowiedź 4xx jest zwykle bardziej zgodna z prawdą. Z drugiej strony nie zwracaj 4xx z powodu tymczasowej awarii bazy danych, jeśli zdarzenie może zakończyć się powodzeniem później. Odpowiedź 5xx daje nadawcy obsługującemu ponawianie szansę na ponowne dostarczenie zdarzenia, chociaż dostawca może stosować własne zasady.
Jak obsługiwać limity czasu?
Wartości limitów czasu webhooków zależą od dostawcy. Nie istnieje uniwersalny limit czasu HTTP używany przez każdą platformę śledzenia, a nadawca może przestać czekać, zanim aplikacja zakończy powolną operację. Traktuj udokumentowany limit czasu nadawcy jako granicę maksymalną, a nie cel. Endpoint powinien zwykle odpowiadać znacznie przed jej osiągnięciem.
Najczęstszym błędem projektowym jest wykonywanie całej pracy zależnej od innych systemów przed potwierdzeniem webhooka. Obsługa może kolejno wywoływać bazę danych, system zarządzania zamówieniami, usługę powiadomień i potok analityczny. Jedna powolna zależność może spowodować, że nadawca zobaczy przekroczenie limitu czasu, mimo że aplikacja ostatecznie zakończy pracę. Nadawca może wtedy ponowić próbę, powodując zduplikowane przetwarzanie lub konkurencyjne aktualizacje.
Ogranicz ścieżkę synchroniczną do pracy potrzebnej do podjęcia bezpiecznej decyzji o akceptacji. Zwykle obejmuje ona uwierzytelnienie żądania, podstawową weryfikację schematu, trwałe zapisanie zdarzenia i publikację w kolejce. Kosztowne wzbogacanie danych, wyszukiwanie informacji u przewoźników, wiadomości do klientów i wywołania interfejsów API stron trzecich umieść za workerem. Monitoruj osobno czas odbierania, weryfikowania, utrwalania i potwierdzania zdarzenia oraz czas jego przetwarzania.
Przekroczenie limitu czasu nie jest tym samym co nieudana operacja biznesowa. Z perspektywy nadawcy przekroczenie limitu czasu zwykle oznacza, że nie otrzymał użytecznej odpowiedzi powodzenia. Twoja usługa mogła pomyślnie zapisać zdarzenie tuż przed zamknięciem połączenia. Dlatego idempotencja i deduplikacja są wymagane nawet wtedy, gdy endpoint wydaje się niezawodny.
Co powoduje ponowienia?
Nadawca webhooka może ponowić próbę po błędzie połączenia, przekroczeniu limitu czasu lub odpowiedzi, którą jego umowa klasyfikuje jako nieudaną. Dokładny harmonogram, maksymalna liczba prób, algorytm wycofywania i okno dostarczania różnią się w zależności od dostawcy. Nie obiecuj stałej liczby ponowień, chyba że określono ją w dokumentacji dostawcy.
Odbiorca powinien założyć, że ponowienia mogą się zdarzać, i celowo się na nie przygotować:
- Używaj identyfikatora zdarzenia, gdy jest dostępny. Zapisuj go z ograniczeniem unikalności lub równoważnym kluczem deduplikacji.
- Zapewnij idempotencję przetwarzania. Dwukrotne zastosowanie tej samej aktualizacji statusu dostawy nie powinno wysłać dwóch wiadomości do klienta, utworzyć dwóch zwrotów ani nieprawidłowo przesunąć zamówienia dalej.
- Zachowuj oryginalne dane lub przydatny rekord audytowy. Umożliwia to odtwarzanie, analizę i uzgadnianie.
- Oddziel akceptację od przetwarzania. Worker może ponawiać wewnętrzne nieudane operacje bez zmuszania nadawcy do powtarzania całej wymiany HTTP.
- Rejestruj kody odpowiedzi i opóźnienia. Wzrost liczby odpowiedzi 5xx, przekroczeń limitu czasu lub zduplikowanych identyfikatorów zdarzeń może ujawnić awarię, zanim użytkownicy zgłoszą brakujące aktualizacje śledzenia.
Zduplikowane zdarzenie powinno zwykle otrzymać odpowiedź powodzenia, jeśli oryginalne zdarzenie zostało już trwale zaakceptowane. Zwracanie błędu dla każdego duplikatu może wywołać niepotrzebne ponowienia. Endpoint może zarejestrować, że zdarzenie było już widziane, pominąć powtórzone działanie biznesowe i zwrócić tę samą klasę powodzenia, która jest używana dla nowo zaakceptowanego zdarzenia.
Kiedy zwracać 4xx, 429 lub 5xx?
Zwracaj 4xx, gdy ponowienie tego samego żądania prawdopodobnie nie rozwiąże problemu. Przykłady obejmują nieprawidłowy podpis, brak wymaganego uwierzytelnienia, nieobsługiwany format danych lub żądanie naruszające trwałą regułę weryfikacji. Przed wyborem 4xx sprawdź, czy nadawca traktuje ten status jako trwałą awarię. Niektóre platformy mają własne zasady dotyczące nieudanych dostaw.
Używaj 429 ostrożnie. HTTP definiuje 429 jako ograniczenie szybkości żądań, a nagłówek Retry-After może wskazywać, kiedy ponowienie może być właściwe. Jednak nie każdy nadawca webhooka interpretuje 429 w ten sam sposób. Jeśli kolejka jest pełna lub usługa przeciążona, potwierdź, że dostawca bezpiecznie ponowi próbę i że jego harmonogram ponowień nie pogorszy przeciążenia. Ograniczona kolejka wejściowa i plan kontroli przeciążenia są zwykle lepsze niż pozwalanie na nieprzewidywalne niepowodzenia żądań.
Zwracaj 5xx, gdy odbiorca nie może bezpiecznie zaakceptować zdarzenia z powodu tymczasowego problemu. Obejmuje to niedostępną bazę danych, nieudany zapis w trwałej kolejce lub błąd wewnętrzny, który uniemożliwił weryfikację albo zapis. Zwracanie 200 przy cichym odrzucaniu zdarzenia utrudnia odzyskanie danych, ponieważ nadawca nie ma powodu, aby spróbować ponownie.
Unikaj polegania na przekierowaniach, takich jak 301, 302 lub 307, przy dostarczaniu webhooków. Obsługa przekierowań różni się między klientami, a przekierowanie podpisanego żądania może wprowadzić niejasności dotyczące miejsca docelowego, metody i treści. Skonfiguruj dostawcę z ostatecznym endpointem HTTPS.
Niezawodna polityka odpowiedzi dla zdarzeń śledzenia
W przypadku większości integracji webhooków śledzenia poniższa polityka jest rozsądnym punktem wyjścia:
- Zwracaj
200lub202po uwierzytelnieniu zdarzenia i jego trwałym zapisaniu lub umieszczeniu w niezawodnej kolejce. - Zwracaj odpowiedź 4xx w przypadku nieprawidłowego podpisu, nieprawidłowego uwierzytelnienia lub trwale nieużytecznych danych, zgodnie z udokumentowanymi zasadami dostawcy.
- Zwracaj 5xx, gdy tymczasowa awaria uniemożliwia trwałą akceptację.
- Zwracaj odpowiedź powodzenia dla bezpiecznie rozpoznanego duplikatu, zapobiegając jednocześnie powtórnym skutkom biznesowym.
- Utrzymuj szybkość obsługi i mierz opóźnienie potwierdzenia.
- Przed uruchomieniem produkcyjnym testuj scenariusze przekroczenia limitu czasu, ponowień, duplikatów, zdarzeń w niewłaściwej kolejności, niepoprawnych danych i awarii dostawcy.
Jeśli integrujesz API śledzenia, zacznij od dokumentacji webhooka dostawcy i potwierdź akceptowane kody powodzenia, metodę podpisywania żądań, limit czasu, wyzwalacze ponowień, schemat danych i identyfikator zdarzenia. W przypadku integracji z 17TRACK właściwym miejscem do zweryfikowania umowy specyficznej dla dostawcy jest oficjalna dokumentacja Tracking API, a nie wnioskowanie na jej podstawie z ogólnych praktyk HTTP.
Lista kontrolna implementacji
- Endpoint jest dostępny przez HTTPS i ma stabilny produkcyjny URL.
- Uwierzytelnienie i weryfikacja podpisu odbywają się przed przetwarzaniem biznesowym.
- Surowe żądanie lub możliwa do zweryfikowania reprezentacja jest przechowywana tam, gdzie jest to wymagane do sprawdzania podpisów i rozwiązywania problemów.
- Zdarzenie jest utrwalane przed wysłaniem odpowiedzi powodzenia.
- Zduplikowane dostawy są bezpieczne i nie powtarzają nieodwracalnych działań.
- Workery mogą ponawiać wewnętrzne przetwarzanie niezależnie od cyklu ponowień HTTP nadawcy.
- Logi zawierają identyfikator zdarzenia, czas dostarczenia, kod odpowiedzi, stan przetwarzania i identyfikator korelacji bez ujawniania sekretów.
- Alerty rozróżniają przekroczenia limitu czasu endpointu, błędy weryfikacji 4xx, awarie 5xx, opóźnienia kolejki i zduplikowane dostawy.
- Udokumentowane zachowanie dostawcy zostało przetestowane na rzeczywistych zdarzeniach lub zdarzeniach w środowisku sandbox.
FAQ
Czy 200 OK jest lepsze niż 202 Accepted dla webhooka?
Żadne z nich nie jest uniwersalnie lepsze. Użyj 200 OK, gdy żądanie zostało zaakceptowane, a integracja traktuje odpowiedź jako ogólne powodzenie. Użyj 202 Accepted, gdy zdarzenie zostało zaakceptowane do przetwarzania asynchronicznego. Potwierdź, że nadawca klasyfikuje wybraną odpowiedź 2xx jako udaną.
Czy endpoint webhooka powinien czekać do pełnego przetworzenia aktualizacji śledzenia?
Zwykle nie. Powinien czekać tylko do momentu uwierzytelnienia, zweryfikowania i trwałego zaakceptowania zdarzenia. Długotrwałe prace powinny zwykle odbywać się po potwierdzeniu, aby powolna zależność nie powodowała możliwego do uniknięcia przekroczenia limitu czasu i ponowienia.
Co powinno się stać, gdy to samo zdarzenie śledzenia nadejdzie dwa razy?
Rozpoznaj je za pomocą identyfikatora zdarzenia dostawcy lub starannie zaprojektowanego równoważnego klucza, pomiń zduplikowane skutki uboczne i zwróć odpowiedź powodzenia, jeśli zdarzenie zostało już zaakceptowane. Dzięki temu ponowienia są bezpieczne bez ukrywania nowych błędów przetwarzania.
Czy nieprawidłowy podpis powinien zwracać 400 czy 401?
Wybór zależy od modelu uwierzytelniania i udokumentowanych oczekiwań dostawcy. Oba kody mogą komunikować odrzucenie, ale spójność jest ważniejsza niż uniwersalny wybór jednego z nich. Nie potwierdzaj zdarzenia, którego autentyczności nie możesz zweryfikować.
Czy odpowiedź 5xx zawsze powoduje ponowienie?
Nie. Wiele systemów webhooków ponawia próby po przekroczeniu limitu czasu i błędach serwera, ale wyzwalacze oraz harmonogramy ponowień zależą od dostawcy. Traktuj ponowienia jako udokumentowane zachowanie integracji i zweryfikuj je w środowisku testowym.
Źródła
- RFC 9110: Semantyka HTTP — definicje odpowiedzi powodzenia, błędów klienta, błędów serwera, przekierowań i obsługi odpowiedzi.
- RFC 6585: Dodatkowe kody statusu HTTP — specyfikacja
429 Too Many Requests. - Dokumentacja Stripe Webhooks — praktyczne wskazówki dotyczące odpowiedzi webhooków, przetwarzania asynchronicznego i obsługi zduplikowanych zdarzeń.
- Dokumentacja GitHub: Obsługa dostaw webhooków — inspekcja dostaw i kwestie operacyjne dotyczące integracji webhooków.
- Dokumentacja 17TRACK Tracking API — dokumentacja specyficzna dla dostawcy, którą należy sprawdzić podczas implementacji integracji Tracking API.


