탐색으로 건너뛰기
Agent Java SDK

Webhook 이벤트 및 청산 경고

판매자 Webhook 이벤트 유형, 멱등성 ID, 청산 경고 필드 및 자금 결과 예시.

Markdown으로 보기

이 페이지는 다음과 같습니다 Agent Java SDK WEBHOOKS.md 커밋 fa6c7b6. 이는 문서 전용 업데이트입니다. 경고 도우미 메서드가 포함된 새로운 SDK 아티팩트가 출시되지 않았습니다.

4가지 이벤트 유형 모두 판매자가 구성한 단일 콜백 URL (agents.webhook_url)을 사용합니다. 신체에 파견 event; 별도의 경고 URL 가 필요하지 않습니다. 예제는 페이로드 구조를 보여주며 테스트 환경에 데이터를 주입하는 데 사용되어서는 안 됩니다.

이벤트 및 멱등성

event의미targetStatus / 중복 제거 키
transfer.completed취소 후 원래 주문에 대한 업데이트를 포함하여 최종 상태를 전송합니다. 반드시 성공하지는 않는다SUCCESS / FAILED / REVERSED; orderType:orderId:targetStatus
reverse.completed역순종료상태SUCCESS / FAILED; orderType:orderId:targetStatus
transfer.dead최종 자금 주문 상태는 재시도 후에도 확인되지 않은 상태로 유지되며 수동 조정이 필요합니다. 확인된 실패는 아니다DEAD; orderType:orderId:targetStatus
liquidation.warning청산 위험 경고, 주문 최종 상태 필드 없음liquidation.warning:notificationId

판매자 경고 이벤트는 liquidation.warning입니다. 사용자 WebSocket data.event는 LIQUIDATION_WARNING로 유지됩니다. 두 채널을 구별되게 유지하십시오.

이전 판매자 알림은 LIQUIDATION_WARNING을 사용했습니다. 고정된 페이로드는 재시도 시 원래 본문을 유지하므로 수신자는 두 이름을 모두 인식해야 합니다. 기존 비즈니스 기록이 대문자 경고 키 접두사를 사용하는 경우 원래 키를 유지하거나 마이그레이션 중에 두 키를 모두 확인하여 알림이 다시 처리되지 않도록 하세요.

현재 WebhookVerifier.idempotencyKey는 자금 이벤트에 대해 orderType:orderId:targetStatus만 추출하고 경고 페이로드에 대해 빈 문자열을 반환합니다. 이 문서 업데이트에서는 경고 도우미 메서드가 포함된 새로운 SDK 아티팩트가 출시되지 않았습니다. 기존 verify 메서드를 계속 사용하여 원시 경고 본문을 확인합니다. 서명 및 소유권을 확인한 후 판매자 비즈니스 코드는 두 이벤트 이름을 모두 인식하고 notificationId가 양의 십진수 문자열인지 확인하고 liquidation.warning:<notificationId>를 구성해야 합니다. 빈 중복 제거 키를 사용하거나 자금 주문 필드를 포함하라는 경고를 요구하지 마세요.

판매자 및 environment 범위 내에서 중복 제거를 유지하고 비즈니스 처리를 통해 원자적으로 커밋합니다. FIRST / UPGRADE / REMINDER notificationId 값이 다른 알림은 독립적입니다. 사용자, 에피소드 또는 eventType별로 그룹화하여 삭제하지 마세요. 빈 키는 유효한 ID를 추출할 수 없음을 의미합니다. SDK는 도우미 키만 반환합니다. 기록을 유지하거나 비즈니스 처리를 수행하지 않습니다. 동일한 정체성을 다른 신체와 충돌로 기록합니다. 처리된 본문을 덮어쓰지 마십시오.

청산 경고 필드 및 예시

필드유형 / 설명
notificationId양의 10진수 문자열입니다. 고유한 알림 ID입니다. 부동 소수점 숫자로 변환하지 마십시오.
eventTypeFIRST: 현재 에피소드의 첫 번째 경고입니다. UPGRADE: 이 에피소드에서는 보통 위험이 높은 위험으로 업그레이드되었습니다. REMINDER: 지속적인 위험을 다시 한번 상기시켜줍니다.
severityNORMAL / HIGH. FIRST는 이미 HIGH일 수 있습니다. UPGRADE는 HIGH입니다. REMINDER는 NORMAL 또는 HIGH일 수 있습니다.
occurredAtJSON 번호; HTTP 배달이 도착했을 때가 아니라 경고가 트리거되었을 때의 Unix 밀리초입니다.
objecttype=CROSS: 교차 마진 계정, symbol, side 및 positionId에 대해 빈 문자열이 있습니다. ISOLATED: 격리 마진 포지션으로, 해당 계약, 사이드, 포지션 ID를 가지고 있습니다.
episode끈; 현재 경고 에피소드. FIRST는 사용자의 첫 번째 경고를 의미하지 않습니다.
stateVersion / configVersion문자열; 업스트림 상태/구성 버전. 이러한 필드를 기반으로 알림을 독립적으로 삭제하지 마세요.
riskRatio / minLargePositionValue / liquidationHighRiskThreshold위험 비율, 일반 경고 임계값 및 고위험 임계값에 대한 십진수 문자열입니다. 정밀도를 유지하세요. 업스트림은 임계값 규칙을 계산합니다.
environmentPRODUCTION / SIMULATED; 서버 이름이 아닌 구성된 자금 환경으로 격리합니다.
agentId / agentCode / agentUserId문자열; 에이전트 ID, 에이전트 코드, 가맹점 사용자 ID입니다.
platformUserId끈; 서비스 내부 user_id가 아닌 바인딩 결과와 일치하는 공개 플랫폼 사용자 ID입니다.
{
  "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"
}

전송 결과 예시

자금 콜백은 기존 유형을 유지합니다. orderId 및 agentId는 JSON 숫자입니다. amount 및 platformUserId는 문자열입니다. 콜백 자금 조달에 경고 문자열 agentId 규칙을 적용하지 마세요. 정수/십진수 유형을 사용하여 정밀도 손실 없이 큰 정수를 읽습니다. completedAt는 UTC RFC3339입니다. ts는 Unix 초입니다.

{
  "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
}

반전 결과 예

{
  "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
}

자금 주문 정지 상태의 예

{
  "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
}

이 예에서는 프로토콜만 보여줍니다. FAILED, rejectCode, rejectMessage 및 failReason의 경우 실제 거부를 반영합니다. 이벤트 이름만으로는 자금이 적립되었음을 증명할 수 없습니다.

서명 확인, 응답 및 재시도