为 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

可选字段

• Headers: 随 webhook 请求发送的 JSON 键值对

  • Common headers include:
    • Authorization: For authentication tokens
    • Content-Type: Usually set to application/json (default)
    • X-Source: To identify the source as LangSmith
  • 如果没有标题，则直接使用 {}

• 请求体模板: 自定义发送到您端点的 JSON 负载

  • 默认：LangSmith 发送定义的负载，并在负载后附加以下额外的键值对：
    • project_name: 触发的告警名称
    • alert_rule_id: 用于标识 LangSmith 告警的 UUID。此 ID 可用作 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 通知，确保通知按预期工作。

故障排除

如果 webhook 通知未被送达：

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

安全注意事项​

• 为您的网络钩子端点使用 HTTPS
• 为您的 webhook 端点实施身份验证
• 考虑在您的请求头中添加共享密钥，以验证网络钩子来源
• 在处理之前验证传入的 webhook 请求

使用 Webhook 向 Slack 发送警报​

以下是配置 LangSmith 警报以使用 chat.postMessage API 向 Slack 频道发送通知的示例。

前置条件

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

步骤 1：创建 Slack 应用​

1. 访问 Slack API 应用程序页面
2. 点击 创建新应用
3. 选择 从零开始
4. 提供 应用名称（例如：\"LangSmith 警报\"）
5. 选择您要安装应用的工作区
6. 点击 创建应用

步骤 2：配置机器人权限​

1. 在你的 Slack 应用配置的左侧边栏中，点击 OAuth & 权限
2. 向下滚动至范围下的机器人令牌范围，并点击添加 OAuth 范围
3. 添加以下作用域:
   • chat:write (以应用身份发送消息)
   • chat:write.public (向应用未加入的频道发送消息)
   • channels:read (查看基本频道信息)

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

1. 滚动到 OAuth & 权限 页面的顶部
2. 点击安装到工作区
3. 审查权限并点击允许
4. 复制出现的Bot User OAuth Token（以xoxb-开头）

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

1. 在 LangSmith 中，导航至您的项目
2. 选择 警报 → 创建警报
3. 定义您的警报指标和条件
4. 在通知部分，选择 Webhook
5. 使用以下设置配置网络钩子：

Webhook URL

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

页眉

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

注意：将 xoxb-your-token-here 替换为您的实际 Bot 用户 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>"
      }
    }
  ]
}

注意：在创建警报时填写 channel_id、alert_name、project_name 和 project_url。您可以在浏览器的地址栏中找到您的 project_url。复制从开头到但不包括任何查询参数的部分。

6. 点击保存以激活网络钩子配置

第 5 步：测试集成​

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

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

创建警报后，您可以选择将其预览链接到 webhook 的请求体中。

要配置此内容：

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

附加资源

• LangSmith 警报文档
• Slack chat.postMessage API 文档
• Slack Block Kit 构建器