Webhooks

概要

Webhooks 支持两类调用场景：告警触发回调与 API 请求成功回调。回调地址仅支持 HTTPS（必须以 https:// 开头）。

在创建告警时可选择触发 Webhook；或在 API 请求完成后触发回调（API 请求成功回调以 request body 形式发送）。

界面示意

下面为 Webhooks 功能的主界面与创建 Webhook 界面示意：

图：Webhooks 主界面

图：创建 Webhook 界面

告警触发回调（Alert Trigger）

回调请求体支持模板变量，常用变量如下：

• ${triggerSource}：触发源（如项目名称）
• ${triggerValue}：当前指标值（原始数值）
• ${triggerValueDisplay}：当前指标值（格式化后，含单位，如 $90.00 / 90%）
• ${ruleName}：告警规则名称
• ${metricName}：监控指标名称
• ${triggerAt}：触发时间（ISO 8601）
• ${ruleThreshold}：告警阈值（原始数值）
• ${ruleThresholdDisplay}：告警阈值（格式化后，含单位，如 $100.00 / 80%）
• ${defaultMessage}：系统默认告警消息
• ${viewLink}：详情页面链接

参考示例：

{
  "event": {
    "type": "alert.triggered",
    "specVersion": "1"
  },
  "data": {
    "metricName": "${metricName}",
    "ruleName": "${ruleName}",
    "triggerSource": "${triggerSource}",
    "triggerValue": "${triggerValue}",
    "triggerValueDisplay": "${triggerValueDisplay}",
    "ruleThreshold": "${ruleThreshold}",
    "ruleThresholdDisplay": "${ruleThresholdDisplay}",
    "triggerAt": "${triggerAt}",
    "defaultMessage": "${defaultMessage}",
    "viewLink": "${viewLink}"
  }
}

注：告警回调支持模板变量替换，但不支持自定义复杂的消息结构；系统将根据模板进行字段填充并投递。

API 请求成功回调（api_request.completed）

该类型回调在 API 请求完成后触发，使用标准 Webhook 请求体结构（Envelope）。不支持自定义消息模板，回调以 application/json 的 request body 发送。

Envelope 字段说明：

字段	类型	说明
event.id	string	事件唯一 ID（UUID）
event.type	string	事件类型
event.specVersion	"1"	请求体规范版本
event.tenantId	string	租户 ID
event.timestamp	string (ISO)	事件产生时间（ISO 8601）
data	object	API 请求成功的负载

Payload 字段（data.*）示例：

字段	说明
completedAt	API 请求完成时间（ISO 8601）
apiKeyId	API Key ID
apiKeyName	API Key 名称（请求发生时的快照）
projectId	项目 ID
projectName	项目名称（请求发生时的快照）
path	HTTP 请求路径
model	调用的模型 ID
isBatch	是否批量调用接口（批量调用价格减半，cost 字段已应用此折扣）
usage	用量明细（tokens、images、videoSeconds 等）
cost	最终费用（含 batch 折扣），单位：元
latencyMs	请求耗时（毫秒）

参考示例：

{
  "event": {
    "id": "9e8f7b2a-4c3d-4f5a-9e1b-7a6b5c4d3e2f",
    "type": "api_request.completed",
    "specVersion": "1",
    "tenantId": "org_abc",
    "timestamp": "2026-04-17T10:23:11.442Z"
  },
  "data": {
    "completedAt": "2026-04-17T10:23:11.089Z",
    "apiKeyId": 42,
    "apiKeyName": "prod-anthropic",
    "projectId": 7,
    "projectName": "Customer Service Bot",
    "path": "/v1/messages",
    "model": "claude-opus-4-5",
    "isBatch": false,
    "usage": {
      "inputTokens": 1234,
      "outputTokens": 567,
      "totalTokens": 1801
    },
    "cost": 0.04218,
    "latencyMs": 2310
  }
}

投递记录

系统记录每次 Webhook 投递请求的结果（含重试情况），在投递记录中可查看：投递时间、目标 URL、HTTP 状态码、响应内容摘要、重试次数与最终状态。

图：Webhooks 投递记录（示意）