使用 Web 钩子

Web 钩子实现了从您的 LangSmith 应用程序到外部服务的事件驱动通信。例如，您可能希望在对 LangSmith 的 API 调用运行完成后，向另一个服务发送更新。许多 LangSmith 端点接受一个 webhook 参数。如果一个可以接受 POST 请求的端点指定了此参数，LangSmith 将在运行完成时发送一个请求。在使用 LangSmith 时，您可能希望在 API 调用完成后使用 Web 钩子来接收更新。Web 钩子对于在运行处理完成后触发您服务中的操作非常有用。要实现这一点，您需要公开一个可以接受 POST 请求的端点，并在 API 请求中将此端点作为 webhook 参数传递。目前，SDK 不提供定义 Web 钩子端点的内置支持，但您可以使用 API 请求手动指定它们。

支持的端点

以下 API 端点接受 webhook 参数：

操作	HTTP 方法	端点
创建运行	`POST`	`/thread/{thread_id}/runs`
创建线程定时任务	`POST`	`/thread/{thread_id}/runs/crons`
流式运行	`POST`	`/thread/{thread_id}/runs/stream`
等待运行	`POST`	`/thread/{thread_id}/runs/wait`
创建定时任务	`POST`	`/runs/crons`
无状态流式运行	`POST`	`/runs/stream`
无状态等待运行	`POST`	`/runs/wait`

在本指南中，我们将展示如何在流式运行后触发 Web 钩子。

设置您的助手和线程

在进行 API 调用之前，请设置您的助手和线程。

Python
JavaScript
CURL

from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
assistant_id = "agent"
thread = await client.threads.create()
print(thread)

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({ apiUrl: <DEPLOYMENT_URL> });
const assistantID = "agent";
const thread = await client.threads.create();
console.log(thread);

curl --request POST \
    --url <DEPLOYMENT_URL>/assistants/search \
    --header 'Content-Type: application/json' \
    --data '{ "limit": 10, "offset": 0 }' | jq -c 'map(select(.config == null or .config == {})) | .[0]' && \
curl --request POST \
    --url <DEPLOYMENT_URL>/threads \
    --header 'Content-Type: application/json' \
    --data '{}'

示例响应：

{
    "thread_id": "9dde5490-2b67-47c8-aa14-4bfec88af217",
    "created_at": "2024-08-30T23:07:38.242730+00:00",
    "updated_at": "2024-08-30T23:07:38.242730+00:00",
    "metadata": {},
    "status": "idle",
    "config": {},
    "values": null
}

在图运行中使用 Web 钩子

要使用 Web 钩子，请在 API 请求中指定 webhook 参数。当运行完成时，LangSmith 会向指定的 Web 钩子 URL 发送一个 POST 请求。例如，如果您的服务器在 https://my-server.app/my-webhook-endpoint 监听 Web 钩子事件，请在请求中包含此 URL：

Python
JavaScript
CURL

input = { "messages": [{ "role": "user", "content": "Hello!" }] }

async for chunk in client.runs.stream(
    thread_id=thread["thread_id"],
    assistant_id=assistant_id,
    input=input,
    stream_mode="events",
    webhook="https://my-server.app/my-webhook-endpoint"
):
    pass

const input = { messages: [{ role: "human", content: "Hello!" }] };

const streamResponse = client.runs.stream(
  thread["thread_id"],
  assistantID,
  {
    input: input,
    webhook: "https://my-server.app/my-webhook-endpoint"
  }
);

for await (const chunk of streamResponse) {
  // 处理流式输出
}

curl --request POST \
    --url <DEPLOYMENT_URL>/threads/<THREAD_ID>/runs/stream \
    --header 'Content-Type: application/json' \
    --data '{
        "assistant_id": <ASSISTANT_ID>,
        "input": {"messages": [{"role": "user", "content": "Hello!"}]},
        "webhook": "https://my-server.app/my-webhook-endpoint"
    }'

Web 钩子负载

LangSmith 以运行的格式发送 Web 钩子通知。请求负载在 kwargs 字段中包含运行输入、配置和其他元数据。除了标准的运行字段外，Web 钩子负载还包括 values、webhook_sent_at 和 error 字段。完整的 Web 钩子负载包含以下字段：

字段	类型	描述
`run_id`	`string` (UUID)	运行的唯一标识符。
`thread_id`	`string` (UUID)	运行所属线程的标识符。
`assistant_id`	`string`	执行运行的助手的标识符。
`status`	`string`	运行的最终状态（例如，`"success"`、`"error"`）。
`created_at`	`string` (datetime)	运行创建的时间戳。
`updated_at`	`string` (datetime)	运行最后更新的时间戳。
`run_started_at`	`string` (datetime)	运行开始执行的时间戳。
`run_ended_at`	`string` (datetime)	运行结束的时间戳。如果运行尚未结束，则省略。
`webhook_sent_at`	`string` (datetime)	Web 钩子请求发送的时间戳。
`metadata`	`JSON object`	与运行关联的自定义元数据。
`kwargs`	`JSON object`	运行输入、配置和其他调用参数。
`values`	`JSON object`	线程最新检查点的状态值。仅对有状态运行存在。
`multitask_strategy`	`string`	运行使用的多任务策略。
`error`	`JSON object \| null`	仅在运行失败时存在。包含 `error`（错误类型）和 `message`（详细信息）字段。

示例负载：

{
  "run_id": "1ef6a5b8-4457-6db0-8b15-cffd3797fa04",
  "thread_id": "9dde5490-2b67-47c8-aa14-4bfec88af217",
  "assistant_id": "agent",
  "status": "success",
  "created_at": "2024-08-30T23:07:38.242730+00:00",
  "updated_at": "2024-08-30T23:07:40.120000+00:00",
  "run_started_at": "2024-08-30T23:07:38.300000+00:00",
  "run_ended_at": "2024-08-30T23:07:40.100000+00:00",
  "webhook_sent_at": "2024-08-30T23:07:40.150000+00:00",
  "metadata": {},
  "kwargs": {
    "input": {
      "messages": [{"role": "user", "content": "Hello!"}]
    }
  },
  "values": {
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hi there! How can I help you today?"}
    ]
  },
  "multitask_strategy": "reject",
  "error": null
}

当运行失败时，error 字段包含有关失败的详细信息：

{
  "error": {
    "error": "TimeoutError",
    "message": "Run exceeded maximum execution time"
  }
}

保护 Web 钩子

为确保只有授权的请求能到达您的 Web 钩子端点，请考虑添加一个安全令牌作为查询参数：

https://my-server.app/my-webhook-endpoint?token=YOUR_SECRET_TOKEN

您的服务器应在处理请求之前提取并验证此令牌。

向 Web 钩子请求添加标头

在 langgraph-api>=0.5.36 中可用。

您可以配置静态标头，以包含在所有出站 Web 钩子请求中。这对于身份验证、路由或向您的 Web 钩子端点传递元数据非常有用。在您的 langgraph.json 文件中添加 webhooks.headers 配置：

{
  "webhooks": {
    "headers": {
      "X-Custom-Header": "my-value",
      "X-Environment": "production"
    }
  }
}

在标头中使用环境变量

要包含机密或特定于环境的值，而无需将其签入配置文件，请使用 ${{ env.VAR }} 模板语法：

{
  "webhooks": {
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
    }
  }
}

出于安全考虑，默认情况下只能引用以 LG_WEBHOOK_ 开头的环境变量。这可以防止意外泄露不相关的环境变量。您可以使用 env_prefix 自定义此前缀：

{
  "webhooks": {
    "env_prefix": "MY_APP_",
    "headers": {
      "Authorization": "Bearer ${{ env.MY_APP_SECRET }}"
    }
  }
}

缺少必需的环境变量将阻止服务器启动，确保您不会在配置不完整的情况下进行部署。

限制 Web 钩子目标

在 langgraph-api>=0.5.36 中可用。

出于安全或合规目的，您可以使用 webhooks.url 配置来限制哪些 URL 是有效的 Web 钩子目标：

{
  "webhooks": {
    "url": {
      "allowed_domains": ["*.mycompany.com", "api.trusted-service.com"],
      "require_https": true
    }
  }
}

可用选项：

选项	描述
`allowed_domains`	主机名允许列表。支持子域名的通配符（例如，`*.mycompany.com`）。
`require_https`	当为 `true` 时，拒绝 `http://` URL。
`allowed_ports`	显式端口允许列表。默认为 443 (https) 和 80 (http)。
`disable_loopback`	当为 `true` 时，禁止相对 URL（内部回环调用）。
`max_url_length`	允许的最大 URL 长度（以字符为单位）。

禁用 Web 钩子

从 langgraph-api>=0.2.78 开始，开发者可以在 langgraph.json 文件中禁用 Web 钩子：

{
  "http": {
    "disable_webhooks": true
  }
}

此功能主要针对自托管部署，平台管理员或开发者可能更倾向于禁用 Web 钩子以简化其安全状况——特别是在他们没有配置防火墙规则或其他网络控制的情况下。禁用 Web 钩子有助于防止不受信任的负载被发送到内部端点。有关完整的配置详情，请参阅配置文件参考。

测试 Web 钩子

您可以使用在线服务测试您的 Web 钩子，例如：

Beeceptor – 快速创建一个测试端点并检查传入的 Web 钩子负载。
Webhook.site – 实时查看、调试和记录传入的 Web 钩子请求。

这些工具可帮助您验证 LangSmith 是否正确触发并向您的服务发送 Web 钩子。

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Agent server

Core capabilities

Develop agents

Deployment guides

Studio

Auth & access control

Server customization

支持的端点

设置您的助手和线程

在图运行中使用 Web 钩子

Web 钩子负载

保护 Web 钩子

向 Web 钩子请求添加标头

在标头中使用环境变量

限制 Web 钩子目标

禁用 Web 钩子

测试 Web 钩子

​支持的端点

​设置您的助手和线程

​在图运行中使用 Web 钩子

​Web 钩子负载

​保护 Web 钩子

​向 Web 钩子请求添加标头

​在标头中使用环境变量

​限制 Web 钩子目标

​禁用 Web 钩子

​测试 Web 钩子

支持的端点

设置您的助手和线程

在图运行中使用 Web 钩子

Web 钩子负载

保护 Web 钩子

向 Web 钩子请求添加标头

在标头中使用环境变量

限制 Web 钩子目标

禁用 Web 钩子

测试 Web 钩子