Webhooks (для интеграторов)

В дополнение к API шлюз умеет присылать вам webhook-события (опционально, включается в настройках кабинета).

События

• payment.succeeded — успешное пополнение.
• payment.failed — отмена/неуспех.
• key.created, key.rotated, key.deleted — события API-ключей.
• key.blocked — ключ заблокирован при balance ≤ 0.
• balance.low — баланс ниже порога (настраивается в кабинете).

Подпись

Тело webhook-а подписывается HMAC-SHA256 секретом, который вы получаете при включении вебхуков. Подпись — в заголовке:

X-Llmbox-Signature: t=1714175400,v1=ad3f...e1

t — unix-timestamp, v1 — hex(hmac_sha256(secret, f"{t}.{body}")). Допуск по времени — 5 минут.

Идемпотентность

В заголовке X-Llmbox-Event-Id приходит UUID, уникальный для события. Сохраняйте у себя, чтобы не обрабатывать повторно.

Ретраи

При 2xx — событие считается доставленным. При 5xx или таймауте (10 секунд) шлюз сделает до 5 ретраев с экспоненциальной задержкой (1m, 5m, 30m, 2h, 12h).

Пример обработчика (FastAPI)

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = b"whsec_..."

@app.post("/llmgw-webhook")
async def hook(req: Request):
    raw = await req.body()
    sig = req.headers.get("X-Llmbox-Signature", "")
    parts = dict(p.split("=", 1) for p in sig.split(","))
    expected = hmac.new(SECRET, f"{parts['t']}.{raw.decode()}".encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        raise HTTPException(403)
    return {"ok": True}