使用 Webhooks

Webhooks 支持从你的 LangSmith 应用程序向外部服务进行事件驱动的通信。例如，当对 LangSmith 的 API 调用完成运行后，你可能希望向另一个服务发送一个更新。许多 LangSmith 的端点接受一个 webhook 参数。如果一个可以接受 POST 请求的端点指定了此参数，LangSmith 将在运行完成时发送一个请求。在使用 LangSmith 时，你可能希望使用 Webhooks 在 API 调用完成后接收更新。Webhooks 非常适合在运行处理完成后触发你服务中的操作。要实现此功能，你需要暴露一个可以接受 POST 请求的端点，并在你的 API 请求中将该端点作为 webhook 参数传递。目前，SDK 没有为定义 webhook 端点提供内置支持，但你可以通过 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`

在本指南中，我们将展示如何在流式运行后触发一个 webhook。

设置你的助手和线程

在进行 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
}

在图运行中使用 Webhook

要使用 webhook，请在你的 API 请求中指定 webhook 参数。当运行完成时，LangSmith 会向指定的 webhook URL 发送一个 POST 请求。例如，如果你的服务器在 https://my-server.app/my-webhook-endpoint 监听 webhook 事件，请在请求中包含此 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"
    }'

Webhook 负载

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

字段	类型	描述
`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)	发送 webhook 请求的时间戳。
`metadata`	`JSON 对象`	与运行关联的自定义元数据。
`kwargs`	`JSON 对象`	运行输入、配置和其他调用参数。
`values`	`JSON 对象`	线程最新检查点的状态值。仅对有状态运行存在。
`multitask_strategy`	`string`	用于此运行的多任务策略。
`error`	`JSON 对象 \| 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"
  }
}

安全 Webhook

为确保只有授权的请求能到达你的 webhook 端点，考虑添加安全令牌作为查询参数：

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

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

为 Webhook 请求添加头部

适用于 langgraph-api>=0.5.36。

你可以配置静态头部，以便包含在所有出站 webhook 请求中。这对于认证、路由或向你的 webhook 端点传递元数据非常有用。在你的 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 }}"
    }
  }
}

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

限制 Webhook 目标

适用于 langgraph-api>=0.5.36。

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

{
  "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 允许的最大字符长度。

禁用 Webhooks

从 langgraph-api>=0.2.78 起，开发者可以在 langgraph.json 文件中禁用 webhooks：

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

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

测试 Webhooks

你可以使用以下在线服务测试你的 webhook：

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

这些工具可帮助你验证 LangSmith 是否正确地触发并向你的服务发送了 webhooks。

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

Edit this page on GitHub or file an issue.

Develop your application

Capabilities

How to build

Auth & access control

Server customization

支持的端点

设置你的助手和线程

在图运行中使用 Webhook

Webhook 负载

安全 Webhook

为 Webhook 请求添加头部

在头部中使用环境变量

限制 Webhook 目标

禁用 Webhooks

测试 Webhooks

​支持的端点

​设置你的助手和线程

​在图运行中使用 Webhook

​Webhook 负载

​安全 Webhook

​为 Webhook 请求添加头部

​在头部中使用环境变量

​限制 Webhook 目标

​禁用 Webhooks

​测试 Webhooks

支持的端点

设置你的助手和线程

在图运行中使用 Webhook

Webhook 负载

安全 Webhook

为 Webhook 请求添加头部

在头部中使用环境变量

限制 Webhook 目标

禁用 Webhooks

测试 Webhooks