使用 Webhook¶

在使用 LangGraph 平台时，您可能希望在 API 调用完成后使用 Webhook 接收更新。Webhook 对于在一次运行处理完成后触发您的服务中的操作非常有用。要实现这一点，您需要公开一个可以接受 POST 请求的端点，并将此端点作为 webhook 参数传递到您的 API 请求中。

目前，SDK 不提供定义 Webhook 端点的内置支持，但您可以使用 API 请求手动指定它们。

支持的端点¶

以下 API 端点接受 webhook 参数

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

设置您的助手和线程¶

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

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 参数。当运行完成时，LangGraph 平台会向指定的 Webhook URL 发送一个 POST 请求。

例如，如果您的服务器在 https://my-server.app/my-webhook-endpoint 监听 Webhook 事件，请在您的请求中包含此 URL

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) {
  // Handle stream output
}

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 负载¶

LangGraph 平台以运行（Run）的格式发送 Webhook 通知。详情请参阅 API 参考。请求负载在 kwargs 字段中包含运行的输入、配置和其他元数据。

保护 Webhook¶

为确保只有授权的请求才能访问您的 Webhook 端点，可以考虑添加一个安全令牌作为查询参数

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

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

禁用 Webhook¶

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

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

此功能主要用于自托管部署，平台管理员或开发者可能希望禁用 Webhook 以简化其安全配置——特别是在他们没有配置防火墙规则或其他网络控制的情况下。禁用 Webhook 有助于防止不受信任的负载被发送到内部端点。

有关完整的配置详细信息，请参阅配置文件参考。

测试 Webhook¶

您可以使用类似以下的在线服务来测试您的 Webhook：

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

这些工具可以帮助您验证 LangGraph 平台是否正确地触发并向您的服务发送 Webhook。