Appearance
Webhook 是 OpenRouter Broadcast 的通用集成方式，支持将 trace 发送到任意可接收 JSON Payload 的 HTTP Endpoint。Trace 以标准 OTLP JSON 格式发送（包含 resourceSpans 数组），兼容任何 OTLP 感知系统。配置只需填写 Endpoint URL，可选配置 HTTP 方法（POST/PUT）和自定义 Header（用于认证）。测试连接时 OpenRouter 发送带 X-Test-Connection: true Header 的空 OTLP Payload，返回 2xx 或 400 均视为通过。自定义元数据通过 trace.metadata.* 命名空间存储在 span attributes 中。
Webhook 允许将 OpenRouter 请求 trace 发送到任意可接收 JSON Payload 的 HTTP Endpoint，适用于自建数据分析管道、内部监控系统或任何支持 HTTP 请求的服务。
配置步骤
第一步：准备 Webhook Endpoint
创建一个 HTTP Endpoint，需满足：
- 接受
application/jsonContent-Type - 成功时返回 2xx 状态码
- 可从公网访问
Endpoint 将接收 OpenTelemetry Protocol (OTLP) 格式的 JSON Payload，兼容任何 OTLP 感知系统。
第二步：在 OpenRouter 开启 Broadcast
前往 Settings > Observability，打开 Enable Broadcast 开关。
第三步：配置 Webhook
点击 Webhook 旁边的编辑图标，填写：
| 字段 | 填写内容 |
|---|---|
| URL | Webhook Endpoint URL（如 https://api.example.com/traces） |
| Method（可选） | HTTP 方法：POST（默认）或 PUT |
| Headers（可选） | 自定义 HTTP Header（JSON 对象格式），用于认证或其他目的 |
认证 Header 示例：
json
{
"Authorization": "Bearer your-token",
"X-Webhook-Signature": "your-webhook-secret"
}第四步：测试并保存
点击 Test Connection 验证配置。测试时 OpenRouter 发送带 X-Test-Connection: true Header 的空 OTLP Payload。你的 Endpoint 返回 2xx 视为通过；400 状态码也可接受（部分 Endpoint 会拒绝空 Payload）。
第五步：验证数据接收
通过 OpenRouter 发送 API 请求，验证 Webhook Endpoint 是否收到 trace 数据。
Payload 格式
Trace 以 OTLP JSON 格式发送，包含 resourceSpans 数组：
json
{
"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" } }
]
}
]
}
]
}
]
}元数据映射
| 键 | OTLP 映射 | 说明 |
|---|---|---|
trace_id | traceId | 将多个请求归入同一 trace |
trace_name | Span name | 根 span 的自定义名称 |
span_name | Span name | 中间 span 的名称 |
generation_name | Span name | LLM 生成 span 的名称 |
parent_span_id | parentSpanId | 链接到已有 span |
自定义元数据以 trace.metadata.* 命名空间存储在 span attributes 中：
json
{
"key": "trace.metadata.order_id",
"value": { "stringValue": "ORD-12345" }
}适用场景
Webhook 目的地适合：
- 自建分析管道：发送到自有数据仓库或分析系统
- 内部监控工具：与私有可观测性平台集成
- 事件驱动架构：基于 LLM 用量触发工作流
- 合规日志：存储到满足特定监管要求的系统
- 开发调试：使用 webhook.site 检查 trace Payload
Privacy Mode
当为此目的地开启 Privacy Mode 时，prompt 和 completion 内容会从 trace 中排除。其他 trace 数据（token 用量、费用、时间、模型信息）仍正常发送。
常见问题
Q: Webhook Endpoint 需要满足什么可用性要求？
A: 生产环境中，确保 Endpoint 高可用并能处理预期的 trace 量。OpenRouter 异步发送 trace，失败时可能不会重试——建议在 Endpoint 侧实现幂等接收和队列缓冲，避免因 Endpoint 短暂不可用丢失 trace。
Q: 如何在 Webhook Payload 中找到我传入的自定义元数据？
A: 自定义键存储在 span 的 attributes 数组中，key 格式为 trace.metadata.{your_key}。例如，trace.order_id 会出现为 { "key": "trace.metadata.order_id", "value": { "stringValue": "..." } }。
Q: Webhook 和 OpenTelemetry Collector 目的地有什么区别？
A: OTLP Collector 专门适配标准 OTLP Collector 端点（直接发送到 /v1/traces），更适合已有 OTel 基础设施的场景。Webhook 更通用，支持自定义 Header 和 HTTP Method，适合需要接入非标准 HTTP 服务的场景。