Web Callouts

Web Callouts 让项目成员能够从 Langfuse UI 中的 trace、observation 或 session 触发一个配置好的后端 HTTP 请求。用它们将调试工作流连接到内部工具、支持系统、事件工作流或自定义调查服务。

与提示词 webhooks不同,Web Callouts 是从 UI 手动触发的。当用户点击该操作时,Langfuse 从后端同步发送请求。

Web Callouts 仅发送标识符:trace/observation/session ID 和 project id。如果你的工作流需要,在你自己的后端从 Langfuse API 获取额外数据。

配置 Web Callout

打开 Project Settings > Integrations > Web Callouts 并创建一个 callout 端点。你需要 Admin/Owner(integrations:CRUD)权限来配置新的 callouts。 Callouts 按项目配置,可被项目中的所有用户调用。

配置:

• Name: 显示在操作菜单中,例如 Add to Support Tool。
• URL: 接受 POST 请求的 HTTP 或 HTTPS 端点。支持自定义端口。
• Success toast message: 在你的端点返回成功响应后显示。
• Enabled: 禁用的 callouts 会从操作菜单中隐藏。
• Request headers: 可选的静态 header,例如 Authorization: Bearer 。

触发 Web Callout

设置后,具有项目读权限的用户可以从以下位置触发 callout:

• trace 详情的操作菜单。
• observation 详情的操作菜单。
• session 详情头部。

当用户点击该操作时,Langfuse 立即发送请求。UI 仅在你的端点返回 2xx 响应后显示成功提示。 请求在 5 秒后超时。调用不会重试,并受到速率限制。

请求负载

Langfuse 发送具有以下结构的 JSON POST 请求:

{
  "version": 1,
  "items": [
    {
      "projectId": "project-id",
      "traceId": "trace-id",
      "observationId": null,
      "sessionId": "session-id"
    }
  ]
}

注意:除 projectId 外,所有 ID 字段都可为空。 Langfuse 在发送请求前会校验 trace、observation 和 session 属于该项目。

端点要求

你的端点必须:

• 接受 Content-Type: application/json 的 POST 请求。
• 在 5 秒内返回任意 HTTP 2xx 状态。

Langfuse 将非 2xx 响应、网络错误、无效 URL 和超时视为失败的 callouts,并显示错误提示。

Web Callouts 不会重试,Langfuse 也不保留投递日志。

身份验证与 Headers

你可以为身份验证配置静态请求 header,例如 Authorization 或 X-API-Key。 Header 值在静态存储时加密,并从 Langfuse 后端发送。编辑现有 header 而不更改其名称时,将值留空会保留已存储的加密值。

Langfuse 自动设置 Content-Type: application/json 和 User-Agent: Langfuse/1.0。 以下 header 名称不能配置:content-length、content-type、cookie 和 host。