设置规则的Webhook通知。

当您在自动化操作中添加 Webhook URL 后，只要您定义的规则与任何新运行匹配，我们将向您的 Webhook 端点发起 POST 请求。

Webhook 有效载荷

我们发送到您的网络钩子端点的有效载荷包含

• "rule_id" 这是发送此有效载荷的自动化任务的ID
• "start_time" 和 "end_time" 是我们找到匹配运行的时间边界
• "runs" 这是一个运行记录数组，其中每个运行记录均为一个字典。如需获取每个运行记录的更多详细信息，我们建议您在端点中使用我们的SDK，通过API来获取。
• "feedback_stats" 这是一个包含各次运行反馈统计信息的字典。该字段的示例有效载荷如下所示。

"feedback_stats": {
    "about_langchain": {
        "n": 1,
        "avg": 0.0,
        "show_feedback_arrow": true,
        "values": {}
    },
    "category": {
        "n": 0,
        "avg": null,
        "show_feedback_arrow": true,
        "values": {
            "CONCEPTUAL": 1
        }
    },
    "user_score": {
        "n": 2,
        "avg": 0.0,
        "show_feedback_arrow": false,
        "values": {}
    },
    "vagueness": {
        "n": 1,
        "avg": 0.0,
        "show_feedback_arrow": true,
        "values": {}
    }
},

正在从S3 URL获取数据

根据您运行时间的远近，inputs_s3_urls 和 outputs_s3_urls 字段可能包含指向实际数据的 S3 URL，而非数据本身。

inputs 和 outputs 可分别通过 inputs_s3_urls 和 outputs_s3_urls 中提供的 ROOT.presigned_url 获取。

这是我们发送到您的网络钩子（Webhook）端点的完整有效载荷示例：

{
  "rule_id": "d75d7417-0c57-4655-88fe-1db3cda3a47a",
  "start_time": "2024-04-05T01:28:54.734491+00:00",
  "end_time": "2024-04-05T01:28:56.492563+00:00",
  "runs": [
    {
      "status": "success",
      "is_root": true,
      "trace_id": "6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "dotted_order": "20230505T051324571809Z6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "run_type": "tool",
      "modified_at": "2024-04-05T01:28:54.145062",
      "tenant_id": "2ebda79f-2946-4491-a9ad-d642f49e0815",
      "end_time": "2024-04-05T01:28:54.085649",
      "name": "Search",
      "start_time": "2024-04-05T01:28:54.085646",
      "id": "6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "session_id": "6a3be6a2-9a8c-4fc8-b4c6-a8983b286cc5",
      "parent_run_ids": [],
      "child_run_ids": null,
      "direct_child_run_ids": null,
      "total_tokens": 0,
      "completion_tokens": 0,
      "prompt_tokens": 0,
      "total_cost": null,
      "completion_cost": null,
      "prompt_cost": null,
      "first_token_time": null,
      "app_path": "/o/2ebda79f-2946-4491-a9ad-d642f49e0815/projects/p/6a3be6a2-9a8c-4fc8-b4c6-a8983b286cc5/r/6ab80f10-d79c-4fa2-b441-922ed6feb630?trace_id=6ab80f10-d79c-4fa2-b441-922ed6feb630&start_time=2023-05-05T05:13:24.571809",
      "in_dataset": false,
      "last_queued_at": null,
      "inputs": null,
      "inputs_s3_urls": null,
      "outputs": null,
      "outputs_s3_urls": null,
      "extra": null,
      "events": null,
      "feedback_stats": null,
      "serialized": null,
      "share_token": null
    }
  ]
}

Webhook 安全性

我们强烈建议您为 Webhook URL 添加一个密钥查询字符串参数，并在处理任何传入请求时验证该参数。这样，即使有人发现了您的 Webhook URL，您也能将那些调用与真实的 Webhook 通知区分开来。

例如

https://api.example.com/langsmith_webhook?secret=38ee77617c3a489ab6e871fbeb2ec87d

Webhook 自定义 HTTP 请求头

如果您希望为网络钩子（webhook）发送特定的请求头，可以针对每个 URL 单独配置。要进行此设置，请点击 URL 输入框旁的 Headers 选项，然后添加您的请求头。

笔记

标头以加密格式存储。

Webhook 交付

向您的 Webhook 端点发送事件时，我们遵循以下准则

• 如果我们无法连接到您的端点，将在声明投递失败之前，最多重试传输连接 2 次。
• 如果您的端点响应时间超过 5 秒，我们将判定投递失败，且不会执行后续操作。
• 如果您的端点在 5 秒内返回 5xx 状态码，我们将最多重试 2 次，并采用指数退避策略。
• 如果您的端点返回 4xx 状态码，我们将声明投递失败且不进行重试。
• 端点在响应体中返回的任何内容都将被忽略

带模态框的示例

设置

以 Modal 为例来说明如何进行设置。Modal 提供了用于推理和微调的自动扩缩 GPU、用于代码智能体的安全容器化环境，以及无服务器 Python Web 端点。本文将重点介绍 Web 端点。

首先，创建一个 Modal 账户。然后，在本地安装 Modal SDK：

pip install modal

要完成账户设置，请运行以下命令：

modal setup

并遵循说明

密钥

接下来，您需要在 Modal 中设置一些密钥。

首先，LangSmith 需要通过传入一个密钥来向 Modal 进行身份验证。 最简单的方法是在查询参数中传入该密钥。 为验证此密钥，我们需要在 Modal 中添加一个密钥以完成校验。 我们将通过创建一个 Modal 密钥来实现这一点。 您可在此处查看有关密钥的说明：此处。 为此，我们将密钥命名为 ls-webhook，并将其设置为一个环境变量，变量名称为 LS_WEBHOOK。

我们还可以设置一个 LangSmith 密钥——幸运的是，目前已有现成的集成模板！

服务

之后，你可以创建一个 Python 文件，该文件将作为你的端点。 以下是一个示例，其中包含注释，用于解释各部分的作用：

from fastapi import HTTPException, status, Request, Query
from modal import Secret, Stub, web_endpoint, Image

stub = Stub("auth-example", image=Image.debian_slim().pip_install("langsmith"))


@stub.function(
    secrets=[Secret.from_name("ls-webhook"), Secret.from_name("my-langsmith-secret")]
)
# We want this to be a `POST` endpoint since we will post data here
@web_endpoint(method="POST")
# We set up a `secret` query parameter
def f(data: dict, secret: str = Query(...)):
    # You can import dependencies you don't have locally inside Modal functions
    from langsmith import Client

    # First, we validate the secret key we pass
    import os

    if secret != os.environ["LS_WEBHOOK"]:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect bearer token",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # This is where we put the logic for what should happen inside this webhook
    ls_client = Client()
    runs = data["runs"]
    ids = [r["id"] for r in runs]
    feedback = list(ls_client.list_feedback(run_ids=ids))
    for r, f in zip(runs, feedback):
        try:
            ls_client.create_example(
                inputs=r["inputs"],
                outputs={"output": f.correction},
                dataset_name="classifier-github-issues",
            )
        except Exception:
            raise ValueError(f"{r} and {f}")
    # Function body
    return "success!"

现在，我们可以使用 modal deploy ... 轻松部署此应用（参见此处的文档）。

你现在应该会看到类似以下的内容：

✓ Created objects.
├── 🔨 Created mount /Users/harrisonchase/workplace/langsmith-docs/example-webhook.py
├── 🔨 Created mount PythonPackage:langsmith
└── 🔨 Created f => https://hwchase17--auth-example-f.modal.run
✓ App deployed! 🎉

View Deployment: https://modal.com/apps/hwchase17/auth-example

需要牢记的重要一点是 https://hwchase17--auth-example-f.modal.run —— 我们创建的用于运行的函数。 注意：此地址并非最终部署 URL，请务必避免误用。

集成它

现在，我们可以使用上面创建的函数 URL，并将其添加为 Webhook。 我们还需记住，要将密钥作为查询参数一同传入。 将所有内容整合起来，其形式应类似于：

https://hwchase17--auth-example-f-dev.modal.run?secret={SECRET}

将 {SECRET} 替换为您创建的用于访问 Modal 服务的密钥。