配置 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 键值对

  • 常用头包括
    • 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 通知，确保通知按预期工作。

故障排除

如果 Webhook 通知未送达

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

安全注意事项

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

使用 Webhook 向 Slack 发送警报

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

先决条件

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

步骤 1：创建 Slack 应用程序

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

步骤 2：配置机器人权限

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

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

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

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

1. 在 LangSmith 中，导航到您的项目
2. 选择警报 → 创建警报
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。您可以在浏览器的 URL 地址栏中找到您的 project_url。复制直到（但不包括）任何查询参数的部分。

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

步骤 5：测试集成

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

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

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

要配置此项

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

附加资源

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