Managed Agents - Webhooks / 托管代理——Webhook

Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state - an alternative to holding an SSE stream or polling. Payloads are thin (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.

当 Managed Agents 资源改变状态时，Anthropic 可以向你的 HTTPS 端点发起 POST——这是保持 SSE 流或轮询之外的另一种选择。负载是薄的（仅含事件类型和资源 ID）；收到后请拉取资源获取当前状态。每次投递都经 HMAC 签名。

Direction matters. This page covers Anthropic -> you notifications about session/vault state. It does not cover third-party -> you webhooks that trigger a session (e.g. a GitHub push handler that calls sessions.create()) - that's ordinary application code on your side with no Anthropic-specific wire format.

方向很重要。本页介绍的是Anthropic -> 你关于会话/保管库状态的通知。它不介绍第三方 -> 你的、用于触发会话的 webhook（例如调用 sessions.create() 的 GitHub push 处理器）——那只是你一侧的普通应用代码，不涉及 Anthropic 特定的报文格式。

Register an endpoint (Console only) / 注册端点（仅限 Console）

Console -> Manage -> Webhooks. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.

Console -> Manage -> Webhooks。目前没有编程式的端点管理 API。密钥轮换也可在同一页面操作。

Verify the signature / 校验签名

Every delivery carries the webhook-id, webhook-timestamp, and webhook-signature headers. Use the SDK's client.beta.webhooks.unwrap() - it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the whsec_ secret from ANTHROPIC_WEBHOOK_SIGNING_KEY. Pass the headers through untouched; don't hand-roll verification against a single X-Webhook-Signature header, which is not the wire format.

每次投递都带有 webhook-id、webhook-timestamp 和 webhook-signature 头。请使用 SDK 的 client.beta.webhooks.unwrap()——它会校验签名、拒绝超过约 5 分钟的旧负载，并返回解析后的事件。它从 ANTHROPIC_WEBHOOK_SIGNING_KEY 读取 whsec_ 密钥。头信息原样透传；不要针对单个 X-Webhook-Signature 头自行实现校验，那不是线上格式。

import anthropic
from flask import Flask, request

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


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.id in seen_event_ids:  # dedupe retries - id is per-event, not per-delivery
        return "", 204
    seen_event_ids.add(event.id)

    match event.data.type:
        case "session.status_idled":
            session = client.beta.sessions.retrieve(event.data.id)
            notify_user(session)
        case "vault_credential.refresh_failed":
            alert_oncall(event.data.id)

    return "", 204

Pass the raw request body to unwrap() - frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.

把原始请求体传给 unwrap()——会重新序列化 JSON 的框架（Express 的 .json()、Flask 的 .get_json()）会改变字节并破坏 MAC。其他语言请在 SDK 仓库中查阅 beta.webhooks.unwrap 绑定（shared/live-sources.md）；不要自行实现校验。

Payload envelope / 负载信封

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

Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the event occurred, not when the delivery was attempted - the webhook-timestamp header is the clock for the attempt (see Delivery behavior).

按 data.type 分支处理，按 data.id 拉取资源，返回任意 2xx 以确认。created_at 是事件发生的时间，而不是尝试投递的时间——webhook-timestamp 头才是投递尝试的时钟（见投递行为一节）。

The top-level id is the same value as the webhook-id header, and it is per event, not per delivery - every retry carries it unchanged. Dedupe on it.

顶层 id 与 webhook-id 头的值相同，它按事件计，而不是按投递计——每次重试都原样携带。以此去重。

Supported data.type values / 支持的 data.type 值

There is deliberately no memory_store.updated. Individual memories and memory versions emit no webhook events at all, and neither do an environment's self-hosted work items. If you need per-memory change tracking, poll the memory-versions endpoints (shared/managed-agents-memory.md).

**刻意不设 memory_store.updated。**单条记忆和记忆版本完全不发出 webhook 事件，环境的自托管工作项也同样不发出。如果需要逐条记忆的变更追踪，请轮询 memory-versions 端点（shared/managed-agents-memory.md）。

These are webhook data.type values - a separate namespace from SSE event types (session.status_idle, span.outcome_evaluation_end, etc. in shared/managed-agents-events.md). Don't reuse SSE constants in webhook handlers.

这些是 webhook 的 data.type 值——与 SSE 事件类型（shared/managed-agents-events.md 中的 session.status_idle、span.outcome_evaluation_end 等）是两个独立的命名空间。不要在 webhook 处理器中复用 SSE 常量。

Delivery behavior & pitfalls / 投递行为与陷阱

• Duplicates. An endpoint can receive the same event more than once; every attempt carries the same top-level event.id (= the webhook-id header). Dedupe on it.
  **重复投递。**同一事件可能不止一次到达端点；每次尝试都带有相同的顶层 event.id（即 webhook-id 头）。以此为去重键。
• Subscription scope. An event reaches only endpoints subscribed to its type at the moment it is emitted. An event emitted while nothing was subscribed is never delivered, and subscribing later does not backfill - subscribe before you need the type.
  订阅范围。事件只送达在事件发出那一刻已订阅其类型的端点。发出时无人订阅的事件永远不会投递，事后订阅也不补发——在需要该类型之前先订阅。
• No ordering guarantee. Events are not delivered in occurrence order: session.status_idled may arrive before session.outcome_evaluation_ended, and a .deleted can arrive before the .archived for the same resource. Drive state from the resource you fetch, not from arrival order.
  **无顺序保证。**事件不按发生顺序投递：session.status_idled 可能先于 session.outcome_evaluation_ended 到达，同一资源的 .deleted 也可能先于 .archived 到达。状态以你取回的资源为准，而不是以到达顺序为准。
• Retries: up to three attempts per endpoint per event, with jittered exponential backoff between 5 and 120 seconds. A response that triggers auto-disable is never retried. After the last attempt fails the event is dropped - not queued, and with no signal that it was lost. Webhooks are not a durable log: if you must observe every transition, reconcile by listing or fetching the resource.
  **重试：**每个端点对每个事件最多尝试三次，采用 5 到 120 秒之间带抖动的指数退避。会触发自动停用的响应绝不重试。最后一次尝试失败后事件即被丢弃——不入队，也没有任何丢失信号。webhook 不是持久日志：如果必须观察到每一次状态迁移，请通过列举或拉取资源来对账。
• webhook-timestamp is re-stamped on every attempt, so retries don't fail the SDK's five-minute freshness check. It times the delivery attempt; use the payload's created_at for when the event occurred.
  webhook-timestamp 在每次尝试时都会重新打戳，因此重试不会导致 SDK 的五分钟新鲜度检查失败。它记录的是投递尝试的时间；事件发生时间请用负载中的 created_at。
• Auto-disable - three triggers, each setting disabled_reason, all reversible from Console (events emitted while disabled are not replayed):
  自动停用——三种触发条件，各自设置 disabled_reason，都可在 Console 中恢复（停用期间发出的事件不会重放）：
  • A 3xx response. Redirects are never followed; disables immediately, on the first attempt. Reason: auto-disabled: endpoint URL returned a redirect (3xx).
    返回 3xx 响应。重定向从不跟随；首次尝试即立即停用。原因：auto-disabled: endpoint URL returned a redirect (3xx)。
  • The URL resolves to a non-public IP at connect time. Disables immediately. Reason: auto-disabled: endpoint URL resolved to an invalid address.
    连接时 URL 解析到非公网 IP。立即停用。原因：auto-disabled: endpoint URL resolved to an invalid address。
  • Continuous failure for a sustained period. Reason: auto-disabled after sustained delivery failures. The trigger is duration, not a delivery count - a single 2xx resets the window, so one flaky event can't disable the endpoint.
    持续一段时间连续失败。原因：auto-disabled after sustained delivery failures。触发条件是持续时间，而不是投递次数——一次 2xx 就会重置时间窗，因此单个不稳定事件无法停用端点。
• Thin payload is intentional. Don't expect stop_reason (list the session's events for that - the session object has no stop_reason field), outcome_evaluations, credential secrets, etc. on the webhook body - fetch the resource.
  **负载刻意做薄。**不要指望 webhook 请求体里会有 stop_reason（这需要列出会话事件——会话对象没有 stop_reason 字段）、outcome_evaluations、凭证机密等内容——去拉取资源。

【评论】"URL 解析到非公网 IP 即自动停用"是一条内置的防 SSRF 措施，阻止 webhook 被用作探测内网地址的跳板；签名校验、五分钟新鲜度窗口与按事件 ID 去重则构成投递完整性的标准组合。