为 LangSmith 警报配置 Webhook 通知

​

概览

​

先决条件

• 一个可以接收 HTTP POST 请求的端点
• 您的接收服务所需的适当身份验证凭据（如果需要）

​

集成配置

​

步骤 1：准备您的接收端点

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

​

步骤 2：配置 Webhook 参数

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

• Header（头部）：随 Webhook 请求发送的 JSON 键值对
  • 常见的头部包括
    • Authorization：用于身份验证令牌
    • Content-Type：通常设置为 application/json (默认)
    • X-Source：用于将来源标识为 LangSmith
  • 如果没有头部，则简单使用 {}
• Request Body Template（请求正文模板）：自定义发送到您的端点的 JSON 有效负载
  • 默认：LangSmith 发送定义的有效负载，并附加以下附加键值对到有效负载中
    • project_name：触发警报的名称
    • alert_rule_id：一个 UUID，用于标识 LangSmith 警报。这可以在 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

​

故障排除

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

​

安全注意事项

• 为您的 Webhook 端点使用 HTTPS
• 为您的 Webhook 端点实施身份验证
• 考虑在头部添加共享密钥以验证 Webhook 来源
• 在处理传入的 Webhook 请求之前进行验证

​

使用 Webhook 将警报发送到 Slack

​

先决条件

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

​

步骤 1：创建 Slack 应用

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

​

步骤 2：配置机器人权限

1. 在您的 Slack 应用程序配置的左侧边栏中，点击 OAuth & Permissions（OAuth 和权限）
2. 向下滚动到 Scopes（作用域）下的 Bot Token Scopes（机器人令牌作用域），然后点击 Add an OAuth Scope（添加 OAuth 作用域）
3. 添加以下作用域
   • chat:write（以应用身份发送消息）
   • chat:write.public（向应用未加入的频道发送消息）
   • channels:read（查看基本频道信息）

​

步骤 3：将应用安装到您的工作区

1. 向上滚动到 OAuth & Permissions（OAuth 和权限）页面的顶部
2. 点击 Install to Workspace（安装到工作区）
3. 查看权限并点击 Allow（允许）
4. 复制出现的 Bot User OAuth Token（机器人用户 OAuth 令牌）（以 xoxb- 开头）

​

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

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

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>"
      }
    }
  ]
}

6. 点击 Save（保存）以激活 Webhook 配置

​

步骤 5：测试集成

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

​

(可选) 步骤 6：在请求正文中链接到警报预览

1. 保存您的警报
2. 在警报表中找到您保存的警报并点击它
3. 复制显示的 URL
4. 点击“编辑警报”
5. 将现有项目 URL 替换为复制的警报预览 URL

​

附加资源

• LangSmith 警报文档
• Slack chat.postMessage API 文档
• Slack Block Kit Builder