B2BB2B LLM

Devoluciones de llamada

Reciba eventos de servidor a servidor idempotentes y firmados y resultados asincrónicos completos.

Devoluciones de llamada

Configurar una URL de devolución de llamada en Perfil → Devoluciones de llamada y resultados asíncronos. Model Gate envía HTTPS POST solicitudes de notificaciones de cuentas habilitadas y solicitudes de inferencia asíncrona nativa completadas. La entrega de devolución de llamada es independiente del procesamiento de inferencia y se ejecuta a través de una cola de trabajadores dedicada y duradera de Model Gate.

URL de devolución de llamada y seguridad saliente

Utilice un punto final HTTPS accesible públicamente. La validación de la URL de devolución de llamada es un límite de seguridad saliente. Se rechazan los rangos de IP de loopback, privado, de enlace local, NAT de nivel de operador, documentación/prueba, multidifusión, no especificados y reservados. El nombre de host se valida cuando se guarda y nuevamente durante la entrega; Las redirecciones se revalidan. No apunte devoluciones de llamada a servicios internos ni redireccionamientos a redes privadas.

Sobre de evento común

Cada devolución de llamada utiliza el mismo sobre:

{
  "event_id": "01J...",
  "event": "account.balance_low",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {}
}

event_id es estable para cada reintento de un evento lógico. Deduplicar entregas por event_id; no infieras la identidad comparando el resto de la carga útil. occurred_at es UTC RFC3339. Las cargas útiles pueden obtener campos adicionales con el tiempo, por lo que los consumidores deben ignorar los campos desconocidos.

Cada entrega también incluye el mismo ID de evento en X-Model-Gate-Event-ID.

Catálogo de eventos

account.balance_low

{
  "event_id": "01J...",
  "event": "account.balance_low",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {
    "balance": "10.1234567890",
    "threshold": "20.0000000000",
    "currency": "USD"
  }
}

key.spend_limit_threshold_reached

{
  "event_id": "01J...",
  "event": "key.spend_limit_threshold_reached",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "key_name": "Bank integration",
    "usage": "80.1234567890",
    "spend_limit": "100.0000000000",
    "threshold_percent": 80,
    "currency": "USD"
  }
}

group.spend_limit_threshold_reached

La carga útil utiliza group_id, group_name, decimal exacto usage, decimal exacto spend_limit, entero threshold_percent, y currency = "USD".

request.completed

{
  "event_id": "01J...",
  "event": "request.completed",
  "occurred_at": "2026-08-28T07:00:00.123456Z",
  "data": {
    "request_id": "01J...",
    "status": "completed",
    "response_status": 200,
    "response": {"id":"msg_...","type":"message"}
  }
}

response_status es anulable cuando no existe ningún estado HTTP ascendente. Los resultados asincrónicos fallidos/cancelados/caducados pueden incluir data.error.

Los valores financieros en las cargas útiles de devolución de llamada son cadenas decimales exactas; no son valores de visualización redondeados en la interfaz de usuario.

Las alertas de umbral se vuelven a armar después de que el valor monitoreado abandona su condición de umbral. El trabajador de umbral evalúa las condiciones aproximadamente una vez por minuto, fuera de la ruta activa de inferencia, por lo que las devoluciones de llamada de umbral no son una señal de cruce de milisegundos en tiempo real.

Formato de solicitud

POST /model-gate/callback HTTP/1.1
Content-Type: application/json
X-Model-Gate-Event-ID: 01J...
X-Model-Gate-Signature: t=1710000000,v1=hex_hmac_sha256

Verificación de firma

Calcule HMAC-SHA256 sobre la cadena exacta <timestamp>.<raw_body> utilizando el secreto de devolución de llamada generado en Perfil. El secreto completo se muestra solo cuando se genera o gira y se almacena cifrado en reposo. Compare la firma hexadecimal en tiempo constante y rechace las marcas de tiempo fuera de su ventana de reproducción aceptada. La marca de tiempo HMAC es específica de un intento de entrega; el event_id permanece estable entre los reintentos.

Entrega, respuesta y reintentos

Cualquier HTTP 2xx la respuesta acepta el evento. HTTP 200 Se recomienda con el cuerpo vacío. Los errores de transporte, los tiempos de espera y todas las respuestas que no sean 2xx son fallas.

Cada evento tiene como máximo 6 intentos en total: el intento inicial más cinco reintentos. Los intentos fallidos del 1 al 5 van seguidos de 5 segundos, 30 segundos, 2 minutos, 10 minutos y 1 hora. Cada intento tiene un duro 15 segundos tiempo de espera general. Después del sexto intento fallido, el evento se vuelve terminal. failed y no hay más reintentos automáticos. Los reclamos de trabajadores obsoletos se devuelven automáticamente a la cola duradera.

No realice trabajos de larga duración antes de responder. Verificar la firma, persistir/deduplicar mediante event_id, devolver 2xxy procesar de forma asincrónica.

Documentación relacionada