为规则设置 webhook 通知

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

Webhook 负载​

发送到您的 webhook 端点的负载包含

• "rule_id" 这是发送此负载的自动化程序的 ID
• "start_time" and "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，而不是数据本身。

The inputs and outputs can be fetched by the ROOT.presigned_url provided in inputs_s3_urls and outputs_s3_urls respectively.

这是我们要发送到您的 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 标头​

如果您希望通过网络钩子发送任何特定的请求头，可以针对每个 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 密钥来实现这一点。 关于密钥的说明，您可以在此处查看：here。 为此，让我们将我们的密钥命名为 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 服务的密钥。