/claude-api

Managed Agents - Webhooks

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.

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.

Register an endpoint (Console only)

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

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.

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.

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).

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.

Supported data.type values

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).

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.

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.
• 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.
• 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.
• 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.
• Auto-disable - three triggers, each setting disabled_reason, all reversible from Console (events emitted while disabled are not replayed):
  • A 3xx response. Redirects are never followed; disables immediately, on the first attempt. Reason: 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.
  • 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.
• 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.