Claude Managed Agents webhooks
Claude Managed Agents webhooks are signed HTTP POST requests that Anthropic sends to your endpoint when agent sessions, scheduled deployments, vaults and other Managed Agents resources change, and they don't report on Messages API calls.
These pages cover the events Anthropic sends about Claude Managed Agents. To start Claude Code from another system's webhook, you call a scheduled task's API trigger instead. Organization webhooks, for enforcement actions on user profiles, are a separate API whose docs say no events are sent yet.
How Claude Managed Agents webhooks work
Webhooks tell you about major state changes in a long-running session without polling, while the session's SSE stream carries its real-time activity. When a subscribed event occurs, Anthropic sends an HTTPS POST with a JSON body to your endpoint, and any 2xx acknowledges it. An endpoint belongs to one workspace and receives only the event types it's subscribed to.
The event type is in data.type, because the top-level type is always event. Payloads are thin: data holds the resource's id, organization_id and workspace_id, plus session_thread_id or vault_id on some events, and you fetch the object with a GET when you need it. Some names differ from the session's event stream, where session.status_idle is the webhook's session.status_idled. Webhooks are in beta, and the docs name no version on a delivery.
Key facts
webhook-signature Format: v1,<base64>, as a space-separated list
{webhook-id}.{webhook-timestamp}.{raw body} The two header values and the body as sent, joined with literal dots.
webhook-timestamp Reject deliveries older than 5 minutes.
npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks Setting up Claude Managed Agents webhooks
- Add an endpoint on the Webhooks page of the Claude Console, after choosing the workspace in the sidebar. It needs an HTTPS URL on port 443 with a publicly resolvable hostname, and the event types it should receive.
- Copy the
whsec_signing secret straight away, because it's shown only once. The Anthropic SDKs read it fromANTHROPIC_WEBHOOK_SIGNING_KEY. - To test on your machine, run
hookdeck listen 3000 claude-managed-agents --path /webhooks/claude-managed-agentsand use the URL the Hookdeck CLI prints. - Anthropic's docs describe no way to resend an event, and subscribing later doesn't backfill one, so subscribe before you need an event type and log what you receive.
Delivery behaviour
not documented the webhooks page gives no limit, so respond as soon as you can Retries up to 3 attempts with jittered exponential backoff between 5 and 120 seconds, all with the same id After retries dropped with no signal that it was lost, so reconcile by listing or fetching through the API Ordering not guaranteed a .deleted event can arrive before the .archived event Known failure modes
From Hookdeck's Claude Managed Agents guide →-
A redirect disables the endpoint
Anthropic never follows redirects, so one
Retries and disabled endpoints →3xxdisables the endpoint on the first attempt, with no retry. Events emitted while it's off aren't replayed, even after you re-enable it in the Console. -
Events lost after three attempts
Anthropic makes up to three attempts, 5 to 120 seconds apart, then drops the event without telling you. Reconcile by listing or fetching the resource through the API.
Recover lost events → -
Duplicate deliveries
An endpoint can receive the same event more than once, and every attempt carries the same top-level
Handle duplicates →id, which is also thewebhook-idheader. Deduplicate on it. -
Out-of-order delivery
Handle ordering →session.status_idledcan arrive before thesession.outcome_evaluation_endedthat came first. Drive your state from the resource you fetch, not from the order events arrive in.
Claude Managed Agents webhook best practices
- Verify every delivery.
Use
unwrap()or a Standard Webhooks library on the raw body, when the request arrives. - Return a 2xx quickly. Anthropic's docs give no time limit, so enqueue the event, respond, and fetch the resource in a worker.
- Deduplicate on the top-level id.
Every attempt carries the same
id, which matcheswebhook-id. Don't usedata.id, because different events share it. - Drive state from the resource you fetch.
Events can arrive in any order, so fetch current state. After a
.deletedevent there's nothing to fetch, so treat the event as final. - Never answer with a redirect.
One
3xxdisables the endpoint at once. To move, add a new endpoint with the new URL and update your signing secret. - Subscribe before you need an event. An event emitted while no endpoint subscribes to its type is never delivered, and subscribing later doesn't backfill it.
Common Claude Managed Agents webhook events
Sessions
session.status_run_started | Agent starts running, on every move into running status |
session.status_idled | Agent stops and waits for input, such as a tool approval |
session.status_terminated | Session ends after an unrecoverable error or being archived |
session.outcome_evaluation_ended | Outcome evaluation finishes for one iteration |
Scheduled deployments
deployment_run.started | Scheduled run starts; manual runs don't send this |
deployment_run.failed | Scheduled run fails to create a session |
deployment.paused | Deployment pauses on request or after an unrecoverable run failure |
Credentials and budgets
vault_credential.refresh_failed | An MCP OAuth credential can no longer be refreshed |
session.budget_reached | Session hits its spending budget and pauses |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
session | 17 | 17 |
deployment | 6 | 6 |
agent | 4 | 4 |
environment | 4 | 4 |
vault_credential | 4 | 4 |
deployment_run | 3 | 3 |
memory_store | 3 | 3 |
vault | 3 | 3 |
In this hub
| Webhook events → | Every covered Claude Managed Agents event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Claude Managed Agents events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks |
Keep a bad deploy from losing your Claude agent events.
Hookdeck Event Gateway gives Anthropic a stable URL to call, verifies the signature on each delivery, queues events and retries to your service on your schedule, so a failure on your side doesn't use up Anthropic's three attempts.