Webhook Ostrzeżenia dotyczące zdarzeń i likwidacji

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ń korzystają z pojedynczego skonfigurowanego wywołania zwrotnego sprzedawcy URL (agents.webhook_url). Przesyłka na ciele event; nie jest wymagane osobne ostrzeżenie URL. Przykłady pokazują strukturę ładunku i nie można ich używać do wstrzykiwania danych do środowiska testowego.

Zdarzenia i idempotencja

Zdarzenie ostrzegające sprzedawcę to liquidation.warning; użytkownik WebSocket data.event pozostaje LIQUIDATION_WARNING. Zachowaj rozróżnienie obu kanałów.

Wykorzystano historyczne powiadomienia sprzedawcy LIQUIDATION_WARNING. Zamrożone ładunki zachowują swoją pierwotną treść przy ponownych próbach, więc odbiorcy muszą rozpoznać obie nazwy. Jeśli istniejące rekordy biznesowe używają przedrostka klucza ostrzegawczego wypełnionego wielkimi literami, zachowaj oryginalny klucz lub sprawdź oba klucze podczas migracji, aby uniknąć ponownego przetwarzania powiadomienia.

Bieżący WebhookVerifier.idempotencyKey wyodrębnia jedynie orderType:orderId:targetStatus dla zdarzeń funduszy i zwraca pusty ciąg znaków dla ładunków ostrzegawczych. W tej aktualizacji dokumentacji nie wydano żadnego nowego SDK artefaktu zawierającego metody pomocnicze ostrzeżeń. Kontynuuj korzystanie z istniejącej metody verify, aby zweryfikować surową treść ostrzeżenia. Po sprawdzeniu podpisu i własności kod biznesowy sprzedawcy musi rozpoznać obie nazwy zdarzeń, sprawdzić, czy notificationId jest dodatnim ciągiem dziesiętno-całkowitym, i skonstruować liquidation.warning:<notificationId>. Nigdy nie używaj pustego klucza deduplikacji ani nie wymagaj, aby ostrzeżenia zawierały pola zamówień środków.

Utrzymaj deduplikację w zakresie sprzedawcy i environment i zatwierdź ją atomowo w ramach przetwarzania biznesowego. FIRST / UPGRADE / REMINDER powiadomienia z różnymi wartościami notificationId są niezależne; nie odrzucaj ich, grupując według użytkownika, odcinka lub eventType. Pusty klucz oznacza, że ​​nie można wyodrębnić prawidłowej tożsamości. SDK zwraca tylko klucz pomocniczy; nie przechowuje dokumentacji ani nie wykonuje przetwarzania biznesowego. Zapisz tę samą tożsamość w innym organie jako konflikt; nie nadpisuj przetworzonej treści.

Pola ostrzeżeń o likwidacji i przykład

{
  "event": "liquidation.warning",
  "notificationId": "68460336",
  "eventType": "FIRST",
  "severity": "NORMAL",
  "occurredAt": 1791875870804,
  "object": {
    "type": "CROSS",
    "symbol": "",
    "side": "",
    "positionId": ""
  },
  "episode": "3",
  "stateVersion": "9",
  "riskRatio": "0.29133109",
  "minLargePositionValue": "0.20000000",
  "liquidationHighRiskThreshold": "0.40000000",
  "configVersion": "8",
  "environment": "PRODUCTION",
  "agentId": "16",
  "agentCode": "DEMO",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872"
}

Przykład wyniku transferu

Wywołania zwrotne funduszy zachowują swoje dotychczasowe typy: orderId i agentId to liczby JSON; amount i platformUserId to ciągi znaków. Nie stosuj konwencji łańcucha ostrzeżenia agentId do wywołań zwrotnych środków. Odczytuj duże liczby całkowite bez utraty precyzji, używając typów całkowitych/dziesiętnych. completedAt to UTC RFC3339; ts to sekundy uniksowe.

{
  "environment": "PRODUCTION",
  "event": "transfer.completed",
  "orderType": "transfer",
  "orderId": 10001,
  "orderNo": "merchant-order-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

Przykład wyniku odwrócenia

{
  "environment": "PRODUCTION",
  "event": "reverse.completed",
  "orderType": "transfer",
  "orderId": 10002,
  "orderNo": "merchant-reverse-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

Przykład stanu martwego zamówienia funduszy

{
  "environment": "PRODUCTION",
  "event": "transfer.dead",
  "orderType": "transfer",
  "orderId": 10003,
  "orderNo": "merchant-order-002",
  "targetStatus": "DEAD",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "order dead",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

Te przykłady pokazują tylko protokół. Dla FAILED, rejectCode, rejectMessage i failReason odzwierciedlają faktyczne odrzucenie. Sama nazwa wydarzenia nie świadczy o zaksięgowaniu środków.

Weryfikacja podpisu, odpowiedzi i ponowne próby