LangSmith Engine Webhook 事件 - Docs by LangChain中文

将 LangSmith 检测到的代理问题转发到事件管理、寻呼或聊天工具中。LangSmith Engine 会在打开新问题，或将新的追踪记录关联到已打开的问题时，向你的端点发送 Webhook 事件。要配置 Webhook 订阅，请打开追踪项目 Engine 标签页中的 Engine Settings 面板。请参阅配置 Engine。

目标可以将事件发送到 Webhook URL 或 Slack 频道。两者使用本页所述的相同事件类型和最低优先级筛选。Slack 目标通过 LangSmith 托管的 Slack 应用发布消息，而不是发送下面的JSON payload，因此签名密钥和自定义标头不适用。要设置 Slack 投递，请参阅通知 Slack 频道。本页其余内容介绍 Webhook URL 目标。

投递

LangSmith 会向你的 Webhook URL 发送带有 JSON body 的 POST 请求。请求使用 Content-Type: application/json，并包含你附加到订阅的所有自定义标头。

Property	Value
Method	`POST`
Body	JSON，见下方的通用信封
Scheme	接受 `http://` 和 `https://`。强烈建议使用 `https://`
Signature	`X-LangSmith-Signature` 标头，使用订阅的签名密钥进行签名
Timeout	每次尝试 20 秒
Attempts	在传输错误、HTTP `408`、`425`、`429` 以及任意 HTTP `5xx` 的情况下，最多尝试 4 次（1 次初始尝试，加上 3 次采用指数退避的重试）。其他 `4xx` 响应会被视为永久性错误，不会重试
Response	仅根据状态代码判断是否成功。忽略响应 body。

重试会投递字节完全相同的 payload，包括相同的 id。请根据 id 去重，以免重试投递在下游产生重复效果。

自定义标头

你可以为每个订阅附加任意标头（例如 Authorization: Bearer …），以便在你的端点对调用方进行身份验证。Content-Type 始终由 LangSmith 设置，无法覆盖。

签名密钥

每个订阅都有一个签名密钥。LangSmith 使用此密钥对原始 Webhook 请求 body 进行签名，并将结果发送到 X-LangSmith-Signature 标头中。标头值格式如下：

sha256=<hex-encoded HMAC-SHA256 digest>

在解析或处理 payload 之前验证签名。HMAC 输入是请求 body 的确切原始字节，HMAC 密钥是订阅的签名密钥。在验证之前，不要先解析 JSON body 再重新序列化。

import hashlib
import hmac
from typing import Optional


def verify_langsmith_signature(
    *,
    body: bytes,
    signing_secret: str,
    signature_header: Optional[str],
) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False

    expected = "sha256=" + hmac.new(
        signing_secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyLangSmithSignature({
  body,
  signingSecret,
  signatureHeader,
}: {
  body: Buffer;
  signingSecret: string;
  signatureHeader: string | undefined;
}) {
  if (!signatureHeader?.startsWith("sha256=")) {
    return false;
  }

  const expected = `sha256=${createHmac("sha256", signingSecret)
    .update(body)
    .digest("hex")}`;

  const expectedBytes = Buffer.from(expected);
  const actualBytes = Buffer.from(signatureHeader);

  return (
    expectedBytes.length === actualBytes.length &&
    timingSafeEqual(expectedBytes, actualBytes)
  );
}

轮换签名密钥

当签名密钥可能已泄露，或组织的凭据轮换策略要求使用新密钥时，请轮换签名密钥。要轮换密钥，请在 Engine Settings 中打开订阅行，点击 Roll signing secret，然后确认。LangSmith 会生成新的签名密钥，并立即将其用于后续 Webhook 投递。轮换完成后，旧密钥会立即停止用于投递签名。轮换密钥后，请更新所有使用新值验证 X-LangSmith-Signature 的消费者。

严重性筛选

每个订阅都有一个介于 0 到 3 之间的 severity_threshold。对于问题事件，仅当问题的 severity 小于或等于该阈值时，才会投递事件。数字越小表示越紧急。

Severity	Meaning
`0`	紧急
`1`	高
`2`	中
`3`	低

例如，severity_threshold: 1 的订阅只会接收 URGENT (0) 和 HIGH (1) 问题的事件。严重性阈值不适用于 issue.agent_run.failed，因为运行失败事件的范围是 Engine 会话，而不是某个具体问题。

事件类型筛选

每个订阅都会指定希望接收的事件类型。未显式指定列表的订阅默认使用 ["issue.created"]。

事件信封

投递到你端点的每个事件都使用相同的外层 JSON 结构。

Field	Type	Description
`id`	UUID	此次投递的唯一标识符。在重试期间保持不变。使用它进行去重。
`type`	string	事件类型。可以是 `issue.created`、`issue.trace.added` 或 `issue.agent_run.failed` 之一。
`created`	integer	事件加入队列时的 Unix 秒数（UTC）。
`request_id`	UUID	同一上游操作触发的所有事件共享的 ID。请参阅批量合并。
`data`	object	事件 payload。始终包含 `data.object`。仅在 `issue.trace.added` 事件中包含 `data.trace`。

Issue `data.object`

对于 issue.created 和 issue.trace.added，data.object 是问题的快照。应将其视为生成事件时问题的权威状态。

Field	Type	Description
`id`	UUID	问题 ID。
`name`	string	问题的简短标题。
`description`	string	面向用户的描述。
`severity`	integer	从 `0`（紧急）到 `3`（低）。请参阅严重性筛选。
`tenant_id`	UUID	问题所属的工作区。
`tenant_name`	string	工作区显示名称。
`session_id`	UUID	问题所属的追踪项目。
`session_name`	string	追踪项目名称。
`url`	string	LangSmith UI 中指向该问题的深层链接。

运行失败 `data.object`

对于 issue.agent_run.failed，data.object 描述失败的 Engine 运行。

Field	Type	Description
`tenant_id`	UUID	运行所属的工作区。
`tenant_name`	string	工作区显示名称。
`session_id`	UUID	运行所属的追踪项目。
`session_name`	string	追踪项目名称。
`url`	string	UI 中指向 LangSmith 项目的深层链接。
`thread_id`	string	Engine 线程 ID。
`run_id`	string	Engine 运行 ID。不可用时省略。
`status`	string	最终运行状态。
`error_message`	string	失败运行的错误文本。不可用时省略。
`occurred_at`	string	失败发生时间的 RFC 3339 时间戳。

`data.trace`

data.trace 仅包含在 issue.trace.added 事件中。

Field	Type	Description
`run_id`	UUID	关联到该问题的运行 ID。
`trace_id`	UUID	包含该运行的追踪记录 ID。
`start_time`	string	运行开始时间的 RFC 3339 时间戳。
`comment`	string \| null	关联追踪记录时记录的可选备注。为空时省略。

批量合并

单个上游操作可能产生多个 Webhook 事件。当 Engine 打开一个新问题并向其附加五条追踪记录时，你会收到一个 issue.created 事件和五个 issue.trace.added 事件，这些事件都共享同一个 request_id。使用 request_id 将它们归并为一条下游通知。

事件类型

以下是 LangSmith Engine 当前发送的完整事件类型集合。未来可能会添加新类型，因此处理程序应忽略未知的 type 值，而不是因此失败。

`issue.created`

LangSmith Engine 创建新问题时发送。省略 data.trace。

{
  "id": "b91c1f0e-7c4a-4f53-9d3e-9f1c8e7a2b10",
  "type": "issue.created",
  "created": 1747238400,
  "request_id": "0d2f4f6a-2a3a-4b6e-9b87-5d5b6e8c9a01",
  "data": {
    "object": {
      "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "name": "工具选择不一致",
      "description": "代理在终止前反复使用完全相同的参数调用搜索工具。",
      "severity": 1,
      "tenant_id": "11111111-2222-3333-4444-555555555555",
      "tenant_name": "Acme 工作区",
      "session_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
      "session_name": "生产 API",
      "url": "https://smith.langchain.com/o/11111111-2222-3333-4444-555555555555/projects/p/66666666-7777-8888-9999-aaaaaaaaaaaa?tab=5&issue=9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
    }
  }
}

`issue.trace.added`

新追踪记录关联到现有问题时发送。data.trace 描述关联的追踪记录。

{
  "id": "c02e3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "type": "issue.trace.added",
  "created": 1747238410,
  "request_id": "0d2f4f6a-2a3a-4b6e-9b87-5d5b6e8c9a01",
  "data": {
    "object": {
      "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "name": "工具选择不一致",
      "description": "代理在终止前反复使用完全相同的参数调用搜索工具。",
      "severity": 1,
      "tenant_id": "11111111-2222-3333-4444-555555555555",
      "tenant_name": "Acme 工作区",
      "session_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
      "session_name": "生产 API",
      "url": "https://smith.langchain.com/o/11111111-2222-3333-4444-555555555555/projects/p/66666666-7777-8888-9999-aaaaaaaaaaaa?tab=5&issue=9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
    },
    "trace": {
      "run_id": "f1e2d3c4-b5a6-9788-6655-44332211ffee",
      "trace_id": "abcdefab-1234-5678-9abc-def012345678",
      "start_time": "2026-05-14T12:30:00Z",
      "comment": "复现了相同的工具循环模式。"
    }
  }
}

`issue.agent_run.failed`

LangSmith Engine 未能完成运行时发送。此事件的范围是会话，因此不包含 data.trace，也不使用严重性筛选。

{
  "id": "4d0e8db2-81e6-4491-b8e5-b13a8f5afc0d",
  "type": "issue.agent_run.failed",
  "created": 1747238500,
  "request_id": "f6bbd48a-0386-403d-9344-31051264b45f",
  "data": {
    "object": {
      "tenant_id": "11111111-2222-3333-4444-555555555555",
      "tenant_name": "Acme 工作区",
      "session_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
      "session_name": "生产 API",
      "url": "https://smith.langchain.com/o/11111111-2222-3333-4444-555555555555/projects/p/66666666-7777-8888-9999-aaaaaaaaaaaa",
      "thread_id": "thread-123",
      "run_id": "run-456",
      "status": "error",
      "error_message": "RuntimeError：缺少 API 密钥",
      "occurred_at": "2026-05-14T12:45:00Z"
    }
  }
}

测试你的端点

在将真实订阅指向你的端点之前，发送一个示例 payload，以验证端点能够接受请求并在 20 秒超时内确认收到：

curl -X POST https://your-endpoint.example.com/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WEBHOOK_SECRET" \
  -d @sample-issue-created.json

使用 issue.created 中的示例 body 作为 sample-issue-created.json。请验证：

自定义 Authorization 标头能够到达，并且与订阅中配置的密钥匹配。
处理程序会根据事件的 id 持久化事件，以便对重试进行去重。
处理程序会在启动缓慢的下游工作之前返回 2xx。

安全性

Webhook URL 会在创建订阅时以及投递时再次进行验证。在 SaaS 中，私有 IP 范围和元数据 IP 范围会被阻止。http:// 和 https:// 均可接受；请使用 https://，以免 payload 和任何自定义标头以明文传输。
LangSmith 使用订阅的签名密钥对 Webhook body 进行签名。在处理 payload 之前验证 X-LangSmith-Signature。
你还可以在订阅上设置自定义标头，例如 Authorization: Bearer …，用于在你的端点进行路由或额外身份验证。
根据事件的 id 进行去重，以免重试投递导致重复通知。

最佳实践

快速确认。 持久化事件后立即响应 2xx。将耗时较长的工作（扇出、寻呼、下游 API 调用）放入队列，以便处理程序保持在 20 秒超时范围内。
容忍未知事件类型。 忽略处理程序无法识别的 type 值。未来可能会添加新的事件类型，恕不另行通知。
容忍新增字段。 使用宽松的架构解析 payload。现有事件类型可能会在不另行通知的情况下新增字段。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​投递

​自定义标头

​签名密钥

​轮换签名密钥

​严重性筛选

​事件类型筛选

​事件信封

​Issue data.object

​运行失败 data.object

​data.trace

​批量合并

​事件类型

​issue.created

​issue.trace.added

​issue.agent_run.failed

​测试你的端点

​安全性

​最佳实践

投递

自定义标头

签名密钥

轮换签名密钥

严重性筛选

事件类型筛选

事件信封

Issue `data.object`

运行失败 `data.object`

`data.trace`

批量合并

事件类型

`issue.created`

`issue.trace.added`

`issue.agent_run.failed`

测试你的端点

安全性

最佳实践