B2BB2B LLM

回调

接收签名的幂等服务器到服务器事件和完成的异步结果。

回调

配置回调 URL 配置文件 → 回调和异步结果。 Model 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。随着时间的推移，有效负载可能会获得额外的字段，因此消费者必须忽略未知的字段。

每次交付还包含相同的事件 ID 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 当不存在上游 HTTP 状态时可为 null。失败/取消/过期的异步结果可能包括 data.error。

回调有效负载中的财务值是精确的十进制字符串；它们不是 UI 四舍五入的显示值。

当监控值离开其阈值条件后，阈值警报将重新启动。阈值工作器在推理热路径之外大约每分钟评估一次条件，因此阈值回调不是实时毫秒交叉信号。

请求格式

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，并异步处理。

相关文档