OpenRouter 安全与可观测

Webhook

2 分钟阅读

Webhook

将追踪发送到任意 HTTP 端点

Webhook 可将追踪发送到任何能够接收 JSON 载荷的 HTTP 端点。这适用于与自定义可观测性系统、内部工具或任何接受 HTTP 请求的服务集成。

第 1 步：设置 webhook 端点

创建一个能够接收带 JSON 载荷的 POST 或 PUT 请求的 HTTP 端点。该端点应：

接受 application/json 内容类型
成功时返回 2xx 状态码
可从公网访问

该端点将以 OpenTelemetry 协议（OTLP）格式接收追踪，因此可与任何支持 OTLP 的系统兼容。

第 2 步：在 OpenRouter 中启用广播

前往设置 > 可观测性（Settings > Observability），打开 启用广播（Enable Broadcast） 开关。

第 3 步：配置 Webhook

点击 Webhook 旁的编辑图标，并填写：

URL：你的 webhook 端点 URL（例如 https://api.example.com/traces）
Method（可选）：使用的 HTTP 方法，POST（默认）或 PUT
Headers（可选）：用于身份验证或其他用途的自定义 HTTP 请求头，格式为 JSON 对象

需要身份验证的端点的请求头示例：

{
  "Authorization": "Bearer your-token",
  "X-Webhook-Signature": "your-webhook-secret"
}

第 4 步：测试并保存

点击 测试连接（Test Connection） 验证配置。仅当测试通过时才会保存配置。测试期间，OpenRouter 会向你的端点发送带有 X-Test-Connection: true 请求头的空 OTLP 载荷。

端点应返回 2xx 状态码，测试才会通过。400 状态码也会被接受，因为部分端点会拒绝空载荷。

第 5 步：发送测试追踪

通过 OpenRouter 发出一次 API 请求，并确认 webhook 端点已收到追踪数据。

载荷格式

追踪以 OTLP JSON 格式发送。每个请求包含一个 resourceSpans 数组，其中的 Span 数据包括：

追踪和 Span ID
时间戳和持续时间
模型和模型服务提供商信息
Token 用量和费用
请求与响应内容（多模态内容已被剥离）

载荷结构示例：

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "openrouter" } }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "abc123...",
              "spanId": "def456...",
              "name": "chat",
              "startTimeUnixNano": "1705312800000000000",
              "endTimeUnixNano": "1705312801000000000",
              "attributes": [
                { "key": "gen_ai.request.model", "value": { "stringValue": "openai/gpt-4" } },
                { "key": "gen_ai.usage.prompt_tokens", "value": { "intValue": "100" } },
                { "key": "gen_ai.usage.completion_tokens", "value": { "intValue": "50" } }
              ]
            }
          ]
        }
      ]
    }
  ]
}

使用场景

Webhook 目标端适用于：

自定义分析流水线：将追踪发送到自有数据仓库或分析系统
内部监控工具：与专有可观测性平台集成
事件驱动架构：基于 LLM 用量触发工作流
合规日志：将追踪存储到满足特定监管要求的系统中
开发与测试：使用 webhook.site 等服务检查追踪载荷

用于生产环境时，请确保 webhook 端点高可用，并能处理预期的追踪量。对于失败的投递，建议在你这一侧实现重试逻辑。

自定义元数据

trace 字段中的自定义元数据会作为 Span 属性包含在发送到 webhook 端点的 OTLP JSON 载荷中。

支持的元数据键

键	OTLP 映射	说明
`trace_id`	`traceId`	将多次请求归入同一条追踪
`trace_name`	Span `name`	根 Span 的自定义名称
`span_name`	Span `name`	层次结构中中间 Span 的名称
`generation_name`	Span `name`	LLM 生成 Span 的名称
`parent_span_id`	`parentSpanId`	关联到追踪层次结构中已有的 Span

示例

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Process this order..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "order_processing_001",
    "trace_name": "Order Processing Pipeline",
    "generation_name": "Extract Order Details",
    "order_id": "ORD-12345",
    "priority": "high"
  }
}

在 Webhook 中访问元数据

自定义元数据键会作为 Span 属性出现在 OTLP 载荷的 trace.metadata.* 命名空间下：

{
  "resourceSpans": [{
    "scopeSpans": [{
      "spans": [{
        "attributes": [
          { "key": "trace.metadata.order_id", "value": { "stringValue": "ORD-12345" } },
          { "key": "trace.metadata.priority", "value": { "stringValue": "high" } }
        ]
      }]
    }]
  }]
}

补充说明

user 字段会映射到 Span 属性中的 user.id
session_id 字段会映射到 Span 属性中的 session.id
模型、Token 和费用数据包含所有标准 GenAI 语义约定（gen_ai.*）

隐私模式

当该目标端启用隐私模式时，追踪中会排除提示词和补全内容。其余追踪数据——Token 用量、费用、时间信息、模型信息以及自定义元数据——仍会正常发送。详情见隐私模式。

上一页W&B Weave