配置 Context Hub 提交 Webhook

Context Hub 提交 Webhook 会在您的工作区中创建代理或技能提交时，通知外部服务。您可以使用它们根据 Context Hub 的变更触发自动化操作，包括通过 LangSmith Fleet 创建的提交。管理 Context Hub Webhook 需要 prompts:update 权限。工作区管理员和工作区编辑者默认拥有此权限。

添加 Webhook

每个 Webhook 都应用于整个工作区。每个已配置的端点都会接收所有代理和技能提交，包括 Fleet 创建的提交。context_hub.commit.created.v1 事件不支持按仓库或事件类型进行筛选。添加 Webhook 的步骤：

在 LangSmith UI 中，前往设置 → 集成 → Context Hub Webhook。
点击 添加 Webhook。
输入一个可从公网访问的 HTTPS URL。
（可选）添加自定义请求标头，例如 Authorization 标头。
点击 添加 Webhook。
复制生成的签名密钥并妥善保存。

您可以添加的订阅数量取决于工作区配置。

管理 Webhook

Webhook 列表会显示端点 URL 和自定义标头名称。标头值和签名密钥会保持隐藏状态，直到您点击 显示密钥。如果您仍拥有管理 Context Hub Webhook 的权限，之后也可以再次显示这些信息。使用 Webhook 上的控件进行管理：

编辑 Webhook：更改 HTTPS URL 或替换自定义标头。编辑不会更改签名密钥。
轮换签名密钥：生成并显示新的签名密钥。LangSmith 会立即使用新密钥进行后续发送，旧密钥将停止工作。请更新所有用于验证 Webhook 的消费者。
删除 Webhook：停止该端点接收来自工作区的后续 Context Hub 提交事件。

发送

LangSmith 会针对每个事件发送一个 JSON POST 请求。自定义标头不能覆盖 Content-Type 或 X-LangSmith-Signature，因为 LangSmith 会在应用自定义标头后设置这两个标头。

属性	值
方法	`POST`
URL	可从公网访问的 HTTPS 端点
内容类型	`application/json`
签名	`X-LangSmith-Signature` 标头，使用 Webhook 的签名密钥进行签名
超时	每次尝试 20 秒
尝试次数	最多 4 次：1 次初始尝试，最多 3 次重试
重试条件	传输失败、HTTP `408`、`425`、`429` 和 `5xx` 响应
永久性响应	其他 `4xx` 响应不会重试
响应处理	状态码低于 `400` 即表示成功。响应正文不会影响成功判定。

重试会包含字节完全相同的请求正文，并保留事件 id。在产生下游影响之前，请根据 id 对事件进行去重。

验证签名

每个请求都包含一个 X-LangSmith-Signature 标头，格式如下：

sha256=<lowercase hex HMAC-SHA256 digest>

使用 Webhook 的签名密钥，根据请求正文中完全相同的原始字节计算 HMAC-SHA256 摘要。在解析 JSON 之前验证签名，并以恒定时间比较完整的标头值。在验证前解析并重新序列化正文可能会改变其字节内容，从而导致签名失效。

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)
  );
}

事件信封

外层的 id、type、created 和 data 信封已固定。事件类型中的 .v1 后缀用于标识 data.commit 架构的版本。

{
  "id": "0198...",
  "type": "context_hub.commit.created.v1",
  "created": 1720000000,
  "data": {
    "commit": {
      "repo_id": "...",
      "repo_handle": "my-agent",
      "repo_type": "agent",
      "commit_hash": "newcommithash0002",
      "parent_commit_hash": "parentcommithash0001",
      "created_at": "2023-11-14T22:13:20Z",
      "created_by": "user@example.com",
      "url": "https://smith.example.com/context/my-agent/newcommithash0002",
      "files_changed": [
        { "path": "skills/kept", "action": "modified" },
        { "path": "skills/added", "action": "added" },
        { "path": "skills/gone", "action": "removed" }
      ]
    }
  }
}

字段	类型	描述
`id`	UUID	唯一的事件标识符，在重试期间保持不变。使用它对事件进行去重。
`type`	string	完整的事件类型。目前为 `context_hub.commit.created.v1`。
`created`	integer	事件进入队列时的 UTC Unix 秒级时间戳。
`data`	object	版本化的事件数据。包含 `data.commit`。

`data.commit`

data.commit 对象描述触发该事件的 Context Hub 提交。

字段	类型	描述
`repo_id`	UUID	Context Hub 仓库 ID。
`repo_handle`	string	仓库句柄。
`repo_type`	string	仓库类型：`agent` 或 `skill`。
`commit_hash`	string	新提交的哈希值。
`parent_commit_hash`	string	父提交的哈希值。初始提交或该值不可用时会省略。
`created_at`	string	创建提交时的 RFC 3339 时间戳。
`created_by`	string	创建提交的 LangSmith 用户 ID。不可用时会省略。
`url`	string	LangSmith UI 中指向该提交的深层链接。
`files_changed`	array	提交中包含的文件变更。每个条目包含 `path` 和 `action`。

`data.commit.files_changed`

每个条目概述一个发生变更的路径，但不包含文件内容。

字段	类型	描述
`path`	string	提交修改的路径。
`action`	string	变更类型：`added`、`modified` 或 `removed`。

处理事件版本

在解析 data.commit 之前，根据完整的事件类型进行分支处理：

if (event.type === "context_hub.commit.created.v1") {
  await handleCommitCreatedV1(event.data.commit);
} else {
  // 安全地忽略未知的事件类型和版本。
}

对 data.commit 的破坏性变更会使用新的事件类型后缀，例如 .v2。请忽略未知类型，不要尝试将其作为 v1 解析；同时允许存在未知字段，以免兼容性新增字段导致处理程序失效。

下一步

使用 Context Hub：创建、检查和提升代理与技能提交。

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

Edit this page on GitHub or file an issue.

Prompts

Context Hub

Tutorials

添加 Webhook

管理 Webhook

发送

验证签名

事件信封

`data.commit`

`data.commit.files_changed`

处理事件版本

下一步

​添加 Webhook

​管理 Webhook

​发送

​验证签名

​事件信封

​data.commit

​data.commit.files_changed

​处理事件版本

​下一步

添加 Webhook

管理 Webhook

发送

验证签名

事件信封

`data.commit`

`data.commit.files_changed`

处理事件版本

下一步