为 LangSmith 警报配置 Webhook 通知

概述

本指南详细介绍了为 LangSmith 警报设置 Webhook 通知的过程。在继续之前，请确保您已按照本指南按照创建警报的通知步骤进行作。Webhook 通过在触发警报条件时发送 HTTP POST 请求来支持与自定义服务和第三方平台的集成。使用 Webhook 将警报数据转发到工单系统、聊天应用程序或自定义监控解决方案。

先决条件

• 可以接收 HTTP POST 请求的终端节点
• 接收服务的适当身份验证凭证（如果需要）

集成配置

第 1 步：准备接收终端节点

在 LangSmith 中配置 webhook 之前，请确保您的接收端点：

• 接受 HTTP POST 请求
• 可以处理 JSON 有效负载
• 可从外部服务访问
• 具有适当的身份验证机制（如果需要）

此外，如果在 LangSmith 的自定义部署中，请确保没有防火墙设置阻止来自 LangSmith 服务的出口流量。

步骤 2：配置 Webhook 参数

在警报的通知部分中，使用以下参数完成 Webhook 配置：

必填字段

• URL：接收终端节点的完整 URL
  • 例：https://api.example.com/incident-webhook

可选字段

• 标头：随 Webhook 请求一起发送的 JSON 键值对

  • 常见标头包括：
    • Authorization：对于身份验证令牌
    • Content-Type：通常设置为application/json（默认）
    • X-Source：将源标识为 LangSmith
  • 如果没有 headers，则只需使用{}

• 请求正文模板：自定义发送到终端节点的 JSON 负载

  • 默认值：LangSmith 发送定义的有效负载，并将以下附加键值对附加到有效负载：
    • project_name：触发的警报的名称
    • alert_rule_id：用于标识 LangSmith 警报的 UUID。这可以用作 Webhook 服务中的重复数据删除键。
    • alert_rule_name：警报规则的名称。
    • alert_rule_type：警报类型（截至 2025 年 4 月 1 日，所有警报的类型均为threshold).
    • alert_rule_attribute：与警报规则关联的属性 -error_count,feedback_score或latency.
    • triggered_metric_value：触发阈值时的指标值。
    • triggered_threshold：触发警报的阈值。
    • timestamp：触发警报的时间戳。

第 3 步：测试 Webhook

单击 Send Test Alert 以发送 Webhook 通知，以确保通知按预期工作。

故障 排除

如果未发送 Webhook 通知：

• 验证 Webhook URL 是否正确且可访问
• 确保所有身份验证标头的格式正确
• 检查您的接收终端节点是否接受 POST 请求
• 检查终端节点的日志中是否有已收到但被拒绝的请求
• 验证您的自定义负载模板是否为有效的 JSON 格式

安全注意事项

• 将 HTTPS 用于 Webhook 终端节点
• 为您的 Webhook 终端节点实施身份验证
• 考虑在标头中添加共享密钥以验证 Webhook 源
• 在处理传入的 Webhook 请求之前对其进行验证

使用 Webhook 向 Slack 发送警报

以下是配置 LangSmith 警报以使用chat.postMessage应用程序接口。

先决条件

• 访问 Slack 工作区
• 用于设置警报的 LangSmith 项目
• 创建 Slack 应用程序的权限

第 1 步：创建 Slack 应用程序

1. 访问 Slack API 应用程序页面
2. 单击 Create New App
3. 从头开始选择
4. 提供应用程序名称（例如，“LangSmith Alerts”）
5. 选择要安装应用程序的工作区
6. 单击 Create App

第 2 步：配置机器人权限

1. 在您的Slack应用程序配置的左侧边栏中，点击OAuth和权限
2. 向下滚动到 Scopes 下的 Bot Token Scopes，然后单击 Add an OAuth Scope
3. 添加以下范围：
   • chat:write（以应用程序形式发送消息）
   • chat:write.public（向应用程序不在的频道发送消息）
   • channels:read（查看基本频道信息）

第 3 步：将应用程序安装到您的工作区

1. 向上滚动到OAuth & Permissions页面的顶部
2. 单击 Install to Workspace
3. 查看权限，然后单击 Allow
4. 复制显示的 Bot User OAuth 令牌（以xoxb-)

第 4 步：在 LangSmith 中配置 Webhook 警报

1. 在 LangSmith 中，导航到您的项目
2. 选择 Alerts → Create Alert
3. 定义警报指标和条件
4. 在通知部分中，选择 Webhook
5. 使用以下设置配置 Webhook：

Webhook URL

https://slack.com/api/chat.postMessage

头

{
  "Content-Type": "application/json",
  "Authorization": "Bearer xoxb-your-token-here"
}

注意：取代xoxb-your-token-here替换为您的实际机器人用户 OAuth 令牌

请求正文模板

{
  "channel": "{channel_id}",
  "text": "{alert_name} triggered for {project_name}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚨{alert_name} has been triggered"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Please check the following link for more information:"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<{project-url}|View in LangSmith>"
      }
    }
  ]
}

注意：填写channel_id,alert_name,project_name和project_url创建警报时。您可以找到project_url在浏览器的 URL 栏中。复制该部分，直到但不包括任何查询参数。

6. 单击 Save 以激活 Webhook 配置

第 5 步：测试集成

1. 在 LangSmith 警报配置中，单击 Test Alert
2. 检查您指定的 Slack 通道以获取测试通知
3. 验证消息是否包含预期的警报信息

（可选）步骤 6：链接到请求正文中的警报预览

创建警报后，您可以选择在 Webhook 的请求正文中链接到其预览。

要配置此项，请执行以下作：

1. 保存提醒
2. 在警报表格中找到已保存的警报，然后单击它
3. 复制 dsiplayed URL
4. 点击 “Edit Alert”
5. 将现有项目 URL 替换为复制的警报预览 URL

其他资源

• LangSmith 警报文档
• Slack chat.postMessage API 文档
• Slack Block Kit 生成器