Claude Managed Agents (beta; available on the first-party Claude API and Claude Platform on AWS, not on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry) offers three ways to learn what an agent is doing: a live Server-Sent Events stream, polling the events list, and webhooks. Webhooks are the right fit for long-running and scheduled work: Anthropic POSTs to an HTTPS endpoint you register whenever a Managed Agents resource changes state, and your infrastructure reacts — no open connections, no polling loops.
Registering an endpoint
Endpoints are registered in the Anthropic Console (Manage → Webhooks); as of July 2026 there is no programmatic endpoint-management API. At creation you receive a signing secret — prefixed whsec_, 32 bytes — that is shown exactly once, so store it in your secret manager immediately. Treat that secret with the same care as an API key: it is what lets your receiver distinguish genuine Anthropic deliveries from forgeries.
What events you receive
Deliveries are deliberately thin: the payload carries the event type and resource IDs only, and you fetch the resource via the API for its current state. This keeps sensitive content out of webhook traffic and means a missed delivery never leaves you with stale data — you always read the live resource. The supported data.type values cover the moments an operator cares about:
| You want to know when… | Webhook event family |
|---|---|
| The agent finished a turn and awaits input | session.status_idled |
| A session started running or was scheduled | session.status_run_started, session.status_scheduled |
| The agent stopped for good | session.status_terminated |
| Rubric-graded work progressed | outcome evaluation events |
| A credential refresh failed | vault_credential.refresh_failed |
| Scheduled deployments fired or failed | deployment / deployment-run lifecycle events |
One naming trap: webhook data.type values are a separate namespace from SSE event types. The stream says session.status_idle; the webhook says session.status_idled. Code that matches strings across both surfaces needs to know they differ. Also note that manual deployment runs (triggered via the API rather than the cron schedule) do not emit deployment_run.* webhook events.
Verifying deliveries
Every delivery is HMAC-signed. The SDK verifies for you: client.beta.webhooks.unwrap() reads the signing key from ANTHROPIC_WEBHOOK_SIGNING_KEY, checks the signature against the raw request body, and rejects payloads older than roughly five minutes to blunt replay attacks. Pass the body exactly as received — parsing and re-serializing JSON before verification will break the signature.
from anthropic import AnthropicAWS
client = AnthropicAWS()
def handle_webhook(raw_body: bytes, headers: dict):
# Verifies HMAC signature using ANTHROPIC_WEBHOOK_SIGNING_KEY;
# raises if invalid or older than ~5 minutes.
event = client.beta.webhooks.unwrap(raw_body, headers)
if event.data.type == "session.status_idled":
... # fetch the session, collect results, send next message
Delivery semantics your receiver must tolerate
Webhook delivery follows the usual distributed-systems rules, and Anthropic documents them explicitly. There is no ordering guarantee — a terminated event can arrive before the idled event that preceded it. Retries reuse the same event.id, so de-duplicate on it and make your handler idempotent (safe to run twice). Redirects count as failures — respond with a 2xx directly, not a 3xx. And endpoints auto-disable after roughly 20 consecutive failed deliveries, which means a broken deploy of your receiver can silently switch notifications off; monitor for that and re-enable in the Console after fixing.
event.id. That pattern survives reordering, retries, and missed deliveries.Webhooks versus streaming
The two are complementary, not competing. An interactive UI showing the agent's progress token by token wants the SSE stream. A pipeline that kicks off a nightly agent run and only cares about "done, failed, or needs input" wants webhooks. Many production setups use both: webhooks drive orchestration, and a stream is opened on demand when a human clicks in to watch.
Where to go next
See session lifecycle and turn management for the SSE side of eventing, vaults for the credential events referenced above, and the webhook automation pattern for building the receiving side well.