B2BB2B LLM

Обратные вызовы

Получайте подписанные идемпотентные межсерверные события и завершенные асинхронные результаты.

Обратные вызовы

Настройте URL-адрес обратного вызова в Профиль → Обратные вызовы и асинхронные результаты. Модель Gate отправляет HTTPS POST запросы на включенные уведомления учетной записи и завершенные собственные запросы асинхронного вывода. Доставка обратного вызова не зависит от обработки вывода и выполняется через выделенную устойчивую рабочую очередь Model Gate.

URL обратного вызова и безопасность исходящего трафика

Используйте общедоступную конечную точку HTTPS. Проверка URL-адреса обратного вызова — это граница безопасности исходящего трафика. Обратный шлейф, частный, локальный канал, NAT операторского уровня, документация/тестирование, многоадресная рассылка, неуказанные и зарезервированные диапазоны IP-адресов отклоняются. Имя хоста проверяется при сохранении и еще раз во время доставки; перенаправления перепроверяются. Не направляйте обратные вызовы на внутренние службы и не перенаправляйте их в частные сети.

Конверт общего мероприятия

Каждый обратный вызов использует один и тот же конверт:

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

event_id стабилен для каждой повторной попытки одного логического события. Дедупликация поставок с помощью event_id; не делайте вывод об идентичности путем сравнения остальной полезной нагрузки. occurred_at это UTC RFC3339. Со временем полезные данные могут получить дополнительные поля, поэтому потребители должны игнорировать неизвестные поля.

Каждая доставка также включает в себя один и тот же идентификатор события в X-Model-Gate-Event-ID.

Каталог мероприятий

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

Полезная нагрузка использует group_id, group_name, точно-десятичный usage, точно-десятичный spend_limit, целое число threshold_percent, и 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 имеет значение NULL, если статус HTTP восходящего потока не существует. Неудачные/отмененные/истёкшие асинхронные результаты могут включать в себя data.error.

Финансовые значения в полезных нагрузках обратного вызова представляют собой точные десятичные строки; они не являются отображаемыми значениями, округленными в пользовательском интерфейсе.

Оповещения о пороговых значениях активируются повторно после того, как отслеживаемое значение выходит за пределы порогового состояния. Обработчик порога оценивает условия примерно раз в минуту за пределами горячего пути вывода, поэтому обратные вызовы порога не являются сигналом пересечения миллисекунд в реальном времени.

Формат запроса

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

Проверка подписи

Вычислить HMAC-SHA256 по точной строке <timestamp>.<raw_body> используя секрет обратного вызова, созданный в профиле. Полный секрет отображается только при создании или ротации и хранится в зашифрованном виде. Сравните шестнадцатеричную подпись в постоянное время и отклоните временные метки за пределами принятого вами окна воспроизведения. Временная метка HMAC зависит от попытки доставки; тот event_id остается стабильным при повторных попытках.

Доставка, ответ и повторные попытки

Любой HTTP 2xx ответ принимает событие. HTTP 200 рекомендуется использовать пустое тело. Ошибки транспорта, тайм-ауты и все ответы, отличные от 2xx, являются сбоями.

Каждое событие имеет не более всего 6 попыток: первоначальная попытка плюс пять повторов. За неудачными попытками 1–5 следуют 5 секунд, 30 секунд, 2 минуты, 10 минут и 1 час.. Каждая попытка имеет трудный 15-секундный общий тайм-аут. После шестой неудачной попытки событие становится терминальным. failed и дальнейшая автоматическая повторная попытка не производится. Устаревшие заявки рабочих автоматически возвращаются в устойчивую очередь.

Не выполняйте длительную работу до ответа. Проверьте подпись, сохраните/дедублируйте ее с помощью event_id, возвращаться 2xxи обрабатывать асинхронно.

Сопутствующая документация