Webhook Weryfikacja podpisu i Idempotencja

Ta strona następuje Agent Java SDK WEBHOOKS.md przy zatwierdzeniu fa6c7b6. To jest aktualizacja zawierająca wyłącznie dokumentację; nie wydano żadnego nowego SDK artefaktu zawierającego metody pomocnicze ostrzegawcze.

Wszystkie cztery typy zdarzeń wykorzystują jedno wywołanie zwrotne sprzedawcy URL i są wysyłane przez treść event. Widzieć Webhook Ostrzeżenia dotyczące zdarzeń i likwidacji dla pól zdarzeń i przykładów ładunku.

Webhook nagłówki

timestamp + nonce + rawBody

Idempotencja zdarzenia

Utrzymuj deduplikację w zakresie sprzedawcy i environment, atomowo z przetwarzaniem biznesowym. Różne wartości notificationId identyfikują niezależne powiadomienia FIRST / UPGRADE / REMINDER; nie odrzucaj powiadomień według użytkownika, odcinka lub eventType. Do deduplikacji nie można użyć pustego klucza idempotencji. SDK zwraca tylko klucz pomocniczy; nie przechowuje ani nie przetwarza danych biznesowych. Zapisz tę samą tożsamość w innym organie jako konflikt; nie nadpisuj przetworzonej treści.

Weryfikacja i odbiór podpisu

Użyj sekretu sprzedawcy API, aby obliczyć HMAC-SHA256 podpis szesnastkowy timestamp + nonce + rawBody. Sprawdź oryginalne odebrane bajty; nie formatuj JSON, nie zmieniaj nazw pól ani nie serializuj najpierw treści.

Najpierw zweryfikuj podpis, a następnie sprawdź okno czasowe (zalecane ± 300 sekund), sprzedawcę i środowisko. Następnie wyodrębnij tożsamość idempotencji i niezawodnie obsłuż powiadomienie. Zachowaj nieznane wartości zdarzeń do celów diagnozy; nigdy nie interpretuj ich jako sukcesu funduszy. Pomocnik weryfikacji nie przeprowadza kontroli okien czasowych, własności ani trwałej deduplikacji.

Zwróć HTTP 2xx po zakończeniu przetwarzania lub potwierdzeniu identycznego duplikatu; w przypadku niepowodzenia zwróć wartość inną niż 2xx. Nadawca ostrzeżenia ma 5-sekundowy limit czasu HTTP i maksymalnie 8 prób. Ponowne próby zatrzymują zamrożone ciało; zmienia się tylko znacznik czasu i wartość jednorazowa podpisu. Odpowiadaj niezwłocznie po rzetelnej akceptacji; długotrwała praca biznesowa może wykorzystywać własne, stałe zadania sprzedawcy.

Powiadomienia sprzedawcy nie zależą od statusu online użytkownika. Wypychanie użytkowników platformy odbywa się wyłącznie w trybie online, bez konieczności odtwarzania w trybie offline; faza pierwsza nie ma skrzynki odbiorczej powiadomień.

Pomyślne odpowiedzi i zatrzymanie ponownych prób

Wezwania zwrotne środków i ostrzeżenia o likwidacji wykorzystują tylko kod stanu HTTP do określenia powodzenia dostawy. Nadawca nie interpretuje treści odpowiedzi code, success, result ani message i nie wymaga ustalonej odpowiedzi OK/success.

Treść odpowiedzi może być pusta, tekstowa lub JSON. Przykładowe pola result mają charakter informacyjny dla sprzedawcy, a nie wymagania protokołu. 202 Accepted zatrzymuje także ponowne próby platformy, więc zwróć je dopiero po niezawodnym zapisaniu powiadomienia w trwałej kolejce zadań sprzedawcy, a nie tylko po uruchomieniu zadania asynchronicznego w pamięci.

Przykłady udanych odpowiedzi

Po zakończeniu przetwarzania biznesowego lub po niezawodnym zapisaniu powiadomienia w oczekującej kolejce sprzedawcy:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Jeżeli treść odpowiedzi nie jest potrzebna:

HTTP/1.1 204 No Content

W przypadku już przetworzonego powiadomienia o identycznej treści pomiń zduplikowane przetwarzanie biznesowe i nadal zwróć 2xx:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Przykłady reakcji na awarię

Jeśli baza danych jest tymczasowo niedostępna, a sprzedawca nie zakończył przetwarzania ani niezawodnie zapisał powiadomienie, zwróć wartość inną niż 2xx, aby platforma mogła spróbować ponownie:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Odrzuć nieprawidłowy podpis bez aktualizacji danych biznesowych lub pomyślnych zapisów deduplikacji:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Te treści odpowiedzi nie powodują zmiany decyzji o ponownym podjęciu próby. Nie należy oczekiwać, że błąd 401 lub 409 trwale zatrzyma ponowne próby; sprawdź podpis, treść powiadomienia lub konfigurację sprzedawcy.

Niepoprawny przykład: poniższa odpowiedź nadal liczy się jako pomyślne dostarczenie. Platforma nie podejmie ponownej próby z powodu success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Jeśli struktura lub globalna procedura obsługi wyjątków otacza niepowodzenia biznesowe w HTTP 200, jawnie ustaw prawidłowy stan błędu w punkcie końcowym wywołania zwrotnego.

Niezawodne potwierdzenie i zduplikowana dostawa

Zalecana kolejność: zweryfikuj podpis i sprawdź czas/sprzedawcę/środowisko → wyodrębnij tożsamość idempotencji → przetwórz dane biznesowe i pomyślne zapisy deduplikacji w transakcji lub niezawodnie zapisz oczekujące zadanie → zwróć 200/204 po pomyślnym zatwierdzeniu. Nie zwracaj 2xx ani nie oznaczaj powiadomienia przetworzonego przed pomyślnym zapisem do bazy danych.

Zduplikowana dostawa może nadal wystąpić po pomyślnym przetworzeniu przez sprzedawcę: odpowiedź może zostać utracona lub platforma może otrzymać wiadomość 2xx, ale wiadomość nie zostanie zachowana SUCCESS. HTTP wywołania zwrotne nie gwarantują jednorazowej dostawy. Utrzymuj deduplikację w obrębie sprzedawcy i zakresu environment. Fundusze wykorzystują orderType:orderId:targetStatus; ostrzeżenia używają liquidation.warning:notificationId. W przypadku identycznego, już przetworzonego ciała, zwróć 2xx bez uznania środków lub ponownego wystawienia przypomnienia. Dla tej samej tożsamości z innym ciałem zarejestruj konflikt i zwróć inny niż 2xx; nie nadpisuj oryginalnego zapisu.

Sukces potwierdzenia oznacza, że ​​sprzedawca otrzymał/przetworzył powiadomienie, a nie, że operacja środków powiodła się. Po zarejestrowaniu prawidłowego powiadomienia o środkach za pomocą targetStatus=FAILED zwróć również 2xx; niepowodzenie zamówienia nie jest powodem do odmowy potwierdzenia zgłoszenia.

Granice finansowania i środowiska

Pierwotny transfer umowy webhook i przepływ queryOrder nie mają automatycznego zastosowania do Finansowania. Potwierdź operacje finansowania przy użyciu queryWalletTransfer i oryginalnego środowiska zamówienia. Wykorzystanie środków finansowych status; oryginalne odpowiedzi na przeniesienie umowy używają orderStatus. Pomyślna odpowiedź HTTP lub code=0 nie jest sama w sobie dowodem przesunięcia środków.

Jawne, symulowane powiadomienia o przeniesieniu kontraktu obejmują environment=SIMULATED. Najpierw zweryfikuj surową treść, a następnie sprawdź użytkownika, kwotę, tożsamość zamówienia i środowisko z zapisanym lokalnym zamówieniem biznesowym.

Przewodnik odzyskiwania środków · Przewodnik po środowisku