订阅 Webhook

会话是长时间运行的交互。虽然大多数实时交互通过 SSE 事件流进行，但 Webhook 会在发生重大状态变更时通知您。

Webhook 事件返回事件的 type 和 id，而非完整对象。当您收到 Webhook 事件时，需要通过 GET 调用直接获取该对象。这样可以避免在重试时传递过时数据，并保持每次投递的数据量较小。

支持的事件类型

注册端点

在 Console 中访问 Manage > Webhooks。

一个 Webhook 端点包含以下内容：

• URL： 必须是使用 443 端口的 HTTPS 地址，且主机名可公开解析。
• 事件类型： 此端点接收的 data.type 值列表。端点仅接收其订阅的事件以及测试事件（参见投递行为）。
• 签名密钥： 创建时生成的一个 32 字节、以 whsec_ 为前缀的密钥。该密钥仅显示一次，请妥善保存以用于验证 Webhook 投递。

验证签名

每次投递都带有 X-Webhook-Signature 标头。使用 SDK 的 unwrap() 辅助方法可一步完成签名验证和事件解析。如果签名无效或负载已超过五分钟，该方法会抛出异常。

将 ANTHROPIC_WEBHOOK_SIGNING_KEY 设置为端点创建时显示的以 whsec_ 为前缀的密钥。

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # 如果签名无效或负载已过期，unwrap() 会抛出异常
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.data.type == "session.status_idled":
        print("session idled:", event.data.id)
    # 处理其他事件类型

    return "", 200

处理事件

解析请求体，根据 data.type 进行分支处理，并通过 ID 获取对应资源。返回任意 2xx 状态码即表示确认。其他任何状态码（包括 3xx）均视为失败，并会触发重试。

每个事件负载都具有相同的结构，包括事件类型、标识符以及对象创建时的时间戳。

{
  "type": "event",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

if event.data.type == "session.status_idled":
    session = client.beta.sessions.retrieve(event.data.id)
    notify_user(session)
return "", 204

顶层的 event.id 对每个事件是唯一的，而非对每次投递唯一。如果您两次收到相同的 event.id，则说明这是一次重试，可以将其丢弃。

投递行为

• 不保证顺序。 即使结果先于空闲状态产生，session.status_idled 也可能在 session.outcome_evaluation_ended 之前到达。如果顺序很重要，请使用 created_at 时间戳进行排序。
• 重试： Anthropic 至少会重试一次。重试投递的是相同的 event.id。
• 不跟随重定向。 3xx 会被视为失败。如果您的端点地址发生变更，请在 Console 中更新 URL。
• 自动禁用： 在大约连续 20 次投递失败后，端点会被自动设置为 disabled 并附带机器可读的 disabled_reason；如果主机名解析为私有 IP 或端点返回重定向，则会立即禁用。解决问题后，请在 Console 中手动重新启用。