为LangSmith警报配置Webhook通知

概览

本指南详细介绍了为LangSmith 警报设置 Webhook 通知的流程。在开始之前，请确保您已按照本指南完成了创建警报过程中通知步骤之前的所有操作。Webhook 可通过在触发警报条件时发送 HTTP POST 请求，实现与自定义服务及第三方平台的集成。您可以利用 Webhook 将警报数据转发至工单系统、聊天应用或自定义监控解决方案。

先决条件

• 一个可接收 HTTP POST 请求的端点
• 接收服务所需的适当认证凭据（如需）

集成配置

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

在 LangSmith 中配置网络钩子（webhook）之前，请确保您的接收端点：

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

此外，如果使用的是 LangSmith 的自定义部署，请确保没有防火墙设置阻止 LangSmith 服务的出站流量。

步骤 2：配置 Webhook 参数

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

必填字段

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

可选字段

• 请求头：随网络钩子（webhook）请求发送的 JSON 键值对

  • 常见请求头包括：
    • Authorization：用于身份验证令牌
    • Content-Type：通常设置为 application/json（默认值）
    • X-Source：标识数据源为 LangSmith
  • 如果没有表头，则直接使用 {}

• 请求体模板：自定义发送到您端点的 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 发送通知，确保通知按预期正常工作。

故障排除

如果网络钩子通知未送达：

• 验证网络钩子（Webhook）URL是否正确且可访问
• 确保所有身份验证请求头格式正确
• 请确认您的接收端点支持 POST 请求
• 检查端点日志，查看已接收但被拒绝的请求
• 验证您的自定义有效载荷模板是否为有效的 JSON 格式

安全注意事项

• 为您的网络钩子端点使用 HTTPS
• 为您的网络钩子端点实现身份验证
• 请考虑在请求头中添加共享密钥，以验证网络钩子（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. 复制显示的机器人用户 OAuth 令牌（以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"
}

Note: Replace xoxb-your-token-here with your actual 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>"
      }
    }
  ]
}

注意：创建警报时，请填写 channel_id、alert_name、project_name 和 project_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 区块工具包构建器