为 LangSmith 警报配置 Webhook 通知

​

概述

​

前提条件

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

​

集成配置

​

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

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

​

步骤 2：配置 Webhook 参数

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

• Headers：与 Webhook 请求一起发送的 JSON 键值对
  • 常见标头包括：
    • Authorization：用于身份验证令牌
    • Content-Type：通常设置为 application/json（默认）
    • X-Source：将源标识为 LangSmith
  • 如果没有标头，则只需使用 {}
• Request Body Template：自定义发送到您端点的 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

​

故障排除

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

​

安全注意事项

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

​

使用 Webhook 向 Slack 发送警报

​

前提条件

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

​

步骤 1：创建 Slack 应用程序

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

​

步骤 2：配置机器人权限

1. 在 Slack 应用配置的左侧边栏中，单击 OAuth & Permissions
2. 向下滚动到 Scopes 下的 Bot Token Scopes 并单击 Add an OAuth Scope
3. 添加以下范围：
   • chat:write（以应用身份发送消息）
   • chat:write.public（向应用不在的频道发送消息）
   • channels:read（查看基本频道信息）

​

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

1. 向上滚动到 OAuth & Permissions 页面的顶部
2. 单击安装到工作区
3. 审查权限并单击允许
4. 复制出现的 Bot User OAuth Token（以 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 替换为您的实际 Bot User OAuth Token

{
  "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. 单击保存以激活 Webhook 配置

​

步骤 5：测试集成

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

​

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

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

​

其他资源

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