Weryfikacja podpisu webhooka i idempotencja

Webhooki powiadamiają backend partnera o asynchronicznych zmianach stanu biznesowego. Ponieważ dostarczenie może być powtarzane, każdy odbiorca musi zweryfikować podpis przed parsowaniem zaufanych danych i musi przetwarzać zdarzenie idempotentnie.

Nagłówki Webhooków

Nagłówek	Opis
X-Agent-Timestamp	Znacznik czasu Unixa w sekundy.
X-Agent-Nonce	Ochrona przed powtórkami.
X-Agent-Sygnatura	HMAC-SHA256 podpis.

timestamp + nonce + rawBody

Używaj dokładnego surowego ciała żądania otrzymanego przez HTTP podczas rekonstrukcji wartości podpisanej. Parsowanie i ponowne serializowanie JSON pierwsze może zmienić odstępy lub kolejność pola i uzyskać inny podpis.

Przepływ weryfikacji

Przeczytaj nagłówki z znacznikiem czasu, nonce i podpisem.
Zdobyć niezmodyfikowany surowy korpus żądania.
Buduj timestamp + nonce + rawBody.
Oblicz HMAC-SHA256 z partnerem API sekretem.
Porównaj obliczone i otrzymane sygnatury za pomocą porównania w czasie stałym.
Stosuj zatwierdzone kontrole aktualności i ponownego użycia w czasie użycia.
Analizuj i przetwarzaj zdarzenie dopiero po pomyślnym sprawdzeniu.

Gdy dostępny jest oficjalny weryfikator Agent SDK , używaj go zamiast utrzymywać kod niezależnego podpisu.

Idempotencja rzędu

Sprawa	Prowadzenie
Początkowa prośba o przeniesienie	Stwórz jedną globalnie unikalną agentOrderNo.
HTTP przerwa	Zapytaj oryginalny agentOrderNo przed utworzeniem nowego.
PROCESSING reakcja	Czekaj na status webhooka lub kolejności zapytania.
Powtarzające się webhooki	Deduplikuj według klucza idempotencji i ostatecznego statusu.

Zalecany rekord idempotencji

Przechowuj wystarczająco dużo informacji, aby rozpoznać powtarzającą się dostawę i bezpiecznie ją odzyskać:

Pole	Cel
Klucz do wydarzenia lub działalności gospodarczej	Jednoznacznie identyfikuje powiadomienie lub operację.
Numer zamówienia partnera	Łączy zdarzenie z oryginalnym żądaniem.
Hash ładunku	Pomaga zidentyfikować sprzeczne powtarzające się ładunki.
Aktualny stan przetwarzania	Rozróżnia otrzymaną, przetwarzaną, sukcesową i nieudaną pracę.
Ostateczny status działalności	Zapobiega podwójnemu zastosowaniu akcji terminalnej.
Przetworzony znacznik czasu	Wspiera politykę dochodzeniową i retencyjną.

Jeśli to możliwe, zatwierdzaj zmianę biznesową i rekord idempotencji w tej samej transakcji. Powtarzające się zdarzenie powinno zwracać już znany wynik, zamiast ponownie stosować saldo, zamówienie lub zmianę użytkownika.

Zasada timeoutu i ponownej próby

Limit HTTP nie dowodzi, że pierwotne żądanie nie powiodło się. Zapytaj operację używając oryginalnego agentOrderNolub poczekaj na jej webhook, zanim zdecydujesz, czy potrzebna jest kolejna akcja. Tworzenie nowego numeru zlecenia biznesowego po każdym przekroczeniu może powodować duplikacje ruchów funduszy.

Lista kontrolna produkcji

Weryfikacja podpisu przed JSON parsowania lub przetwarzania biznesowego.
Zachowanie surowego ciała niezależnie od przeanalizowanego ładunku.
Odrzucanie przestarzałych lub powtarzanych żądań zgodnie z zatwierdzoną polityką integracji.
Zapewnienie bezpiecznego przetwarzania zdarzeń dla powtarzających się i niekolejnych dostaw.
Rejestruj identyfikatory zdarzeń, numery zamówień partnerów, wyniki przetwarzania oraz czas żądań.
Redakcja sekretów i wartości sygnatur z logów i załączników wsparcia.

Sekrety i podpisywanie HMAC

Chroń API sekret używany do weryfikacji żądań i webhooków.

Agent SDK Przegląd

Przejrzyj cały proces integracji backendu.

SDK Rozwiązywanie problemów