Webhook Eventos y advertencias de liquidación

Esta página sigue Agent Java SDK WEBHOOKS.md en el compromiso fa6c7b6. Esta es una actualización de documentación únicamente; no se lanzó ningún nuevo artefacto SDK que contenga métodos auxiliares de advertencia.

Los cuatro tipos de eventos utilizan la devolución de llamada única configurada por el comerciante URL (agents.webhook_url). Despacho en el cuerpo event; no se requiere ninguna advertencia separada URL. Los ejemplos muestran la estructura de carga útil y no deben usarse para inyectar datos en un entorno de prueba.

Eventos e idempotencia

El evento de advertencia del comerciante es liquidation.warning; el usuario WebSocket data.event permanece LIQUIDATION_WARNING. Mantenga los dos canales distintos.

Notificaciones comerciales históricas utilizadas LIQUIDATION_WARNING. Las cargas útiles congeladas conservan su cuerpo original en los reintentos, por lo que los receptores deben reconocer ambos nombres. Si los registros comerciales existentes utilizan un prefijo de clave de advertencia en mayúscula, conserve la clave original o verifique ambas claves durante la migración para evitar procesar la notificación nuevamente.

El WebhookVerifier.idempotencyKey actual solo extrae orderType:orderId:targetStatus para eventos de fondos y devuelve una cadena vacía para cargas útiles de advertencia. No se lanzó ningún nuevo artefacto SDK que contenga métodos auxiliares de advertencia con esta actualización de la documentación. Continúe usando el método verify existente para verificar el cuerpo de advertencia sin formato. Después de las comprobaciones de firma y propiedad, el código comercial del comerciante debe reconocer ambos nombres de eventos, validar que notificationId es una cadena de números enteros decimales positivos y construir liquidation.warning:<notificationId>. Nunca utilice una clave de deduplicación vacía ni solicite advertencias para contener campos de orden de fondos.

Persista la deduplicación dentro del alcance del comerciante y environment y comprométala atómicamente con el procesamiento comercial. Las notificaciones FIRST / UPGRADE / REMINDER con diferentes valores notificationId son ​​independientes; no los descartes agrupándolos por usuario, episodio o eventType. Una clave vacía significa que no se pudo extraer una identidad válida. El SDK solo devuelve una clave auxiliar; no conserva registros ni realiza procesamiento comercial. Registrar la misma identidad con un organismo diferente como conflicto; no sobrescriba el cuerpo procesado.

Campos de advertencia de liquidación y ejemplo

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

Ejemplo de resultado de transferencia

Las devoluciones de llamadas de fondos conservan sus tipos existentes: orderId y agentId son ​​números JSON; amount y platformUserId son ​​cadenas. No aplique la convención de cadena de advertencia agentId a las devoluciones de llamadas de fondos. Lea números enteros grandes sin pérdida de precisión utilizando tipos enteros/decimales. completedAt es UTC RFC3339; ts son ​​segundos de 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
}

Ejemplo de resultado de reversión

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

Ejemplo de estado muerto de orden de fondos

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

Estos ejemplos muestran únicamente el protocolo. Para FAILED, rejectCode, rejectMessage y failReason reflejan el rechazo real. El nombre del evento por sí solo no prueba que se hayan acreditado los fondos.

Verificación de firma, respuestas y reintentos