B2BB2B LLM

Retornos de chamada

Receba eventos assinados e idempotentes de servidor para servidor e resultados assíncronos concluídos.

Retornos de chamada

Configure um URL de retorno de chamada em Perfil → Retornos de chamada e resultados assíncronos. Modelo Gate envia HTTPS POST solicitações de notificações de conta habilitadas e solicitações de inferência assíncrona nativa concluídas. A entrega de retorno de chamada é independente do processamento de inferência e é executada por meio de uma fila de trabalho dedicada e durável do Model Gate.

URL de retorno de chamada e segurança de saída

Use um endpoint HTTPS acessível publicamente. A validação de URL de retorno de chamada é um limite de segurança de saída. Loopback, privado, link local, NAT de nível de operadora, documentação/teste, multicast, intervalos de IP não especificados e reservados são rejeitados. O nome do host é validado quando salvo e novamente durante a entrega; os redirecionamentos são revalidados. Não aponte retornos de chamada para serviços internos ou redirecionamentos para redes privadas.

Envelope de evento comum

Cada retorno de chamada usa o mesmo envelope:

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

event_id é estável para cada nova tentativa de um evento lógico. Desduplicar entregas por event_id; não infira a identidade comparando o restante da carga útil. occurred_at é UTC RFC3339. As cargas úteis podem ganhar campos adicionais ao longo do tempo, portanto os consumidores devem ignorar os campos desconhecidos.

Cada entrega também inclui o mesmo ID de evento em 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

A carga útil usa group_id, group_name, decimal exato usage, decimal exato spend_limit, inteiro threshold_percent, e 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 é anulável quando não existe nenhum status HTTP upstream. Os resultados assíncronos com falha/cancelados/expirados podem incluir data.error.

Os valores financeiros em cargas de retorno de chamada são strings decimais exatas; eles não são valores de exibição arredondados pela interface do usuário.

Os alertas de limite são rearmados depois que o valor monitorado sai da sua condição de limite. O trabalhador de limite avalia as condições aproximadamente uma vez por minuto, fora do caminho ativo de inferência, portanto, os retornos de chamada de limite não são um sinal de cruzamento de milissegundos em tempo real.

Formato de solicitação

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

Verificação de assinatura

Calcule HMAC-SHA256 na string exata <timestamp>.<raw_body> usando o segredo de retorno de chamada gerado no Perfil. O segredo completo é mostrado apenas quando gerado ou girado e é armazenado criptografado em repouso. Compare a assinatura hexadecimal em tempo constante e rejeite os carimbos de data e hora fora da janela de reprodução aceita. O carimbo de data/hora do HMAC é específico para uma tentativa de entrega; o event_id permanece estável entre novas tentativas.

Entrega, resposta e novas tentativas

Qualquer HTTP 2xx resposta aceita o evento. HTTP 200 com o corpo vazio é recomendado. Erros de transporte, tempos limite e todas as respostas não 2xx são falhas.

Cada evento tem no máximo 6 tentativas no total: a tentativa inicial mais cinco tentativas. As tentativas fracassadas de 1 a 5 são seguidas por 5 segundos, 30 segundos, 2 minutos, 10 minutos e 1 hora. Cada tentativa tem uma dificuldade 15 segundos tempo limite geral. Após a sexta tentativa fracassada, o evento se torna terminal failed e não há mais tentativas automáticas. As declarações de trabalho obsoletas são automaticamente retornadas para a fila durável.

Não execute trabalhos de longa duração antes de responder. Verifique a assinatura, persista/desduplique por event_id, retornar 2xxe processar de forma assíncrona.

Documentação relacionada