Перейти к содержимому
MGModel Gate
ВойтиНачать работу

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

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

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

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

Используйте публично доступный HTTPS-эндпоинт. Проверка URL обратного вызова — граница безопасности исходящих соединений. Отклоняются loopback, частные, link-local, CGNAT, документальные/тестовые, multicast, неопределённые и зарезервированные диапазоны 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 и обрабатывайте асинхронно.

Связанные документы