B2BB2B LLM

Обратни повиквания

Получавайте подписани, идемпотентни събития от сървър към сървър и завършени асинхронни резултати.

Обратни повиквания

Конфигурирайте URL адрес за обратно извикване в Профил → Обратни повиквания и асинхронни резултати. Model Gate изпраща HTTPS POST заявки за активирани известия за акаунти и завършени собствени заявки за асинхронен извод. Доставката на обратно извикване е независима от обработката на изводи и преминава през специална издръжлива работна опашка на Model Gate.

URL адрес за обратно извикване и изходяща сигурност

Използвайте публично достъпна HTTPS крайна точка. Проверката на URL за обратно извикване е граница на изходяща сигурност. Loopback, частен, локален за връзка, 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 е nullable, когато не съществува 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и обработват асинхронно.

Свързана документация