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.

44 events covered

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

Signature header
webhook-signature

Format: v1,<base64>, as a space-separated list

Scheme
HMAC-SHA256, base64
Signed material
{webhook-id}.{webhook-timestamp}.{raw body}

The two header values and the body as sent, joined with literal dots.

How events are identified
data.type field in the body
Body format
JSON

Content type: application/json.

Send timestamp
webhook-timestamp

Reject deliveries older than 5 minutes.

Other headers
webhook-id, webhook-timestamp
Envelope
type, id, created_at, data
Agent skill
npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks

Verify 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 from ANTHROPIC_WEBHOOK_SIGNING_KEY.
  • To test on your machine, run hookdeck listen 3000 claude-managed-agents --path /webhooks/claude-managed-agents and 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

  1. A redirect disables the endpoint

    Anthropic never follows redirects, so one 3xx disables 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.

    Retries and disabled endpoints →
  2. 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 →
  3. Duplicate deliveries

    An endpoint can receive the same event more than once, and every attempt carries the same top-level id, which is also the webhook-id header. Deduplicate on it.

    Handle duplicates →
  4. Out-of-order delivery

    session.status_idled can arrive before the session.outcome_evaluation_ended that came first. Drive your state from the resource you fetch, not from the order events arrive in.

    Handle ordering →

Claude Managed Agents webhook best practices

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

session.status_run_started · .status_idled · .budget_reached · .status_rescheduled +13

17 17
deployment

deployment.created · .updated · .paused · .unpaused +2

6 6
agent

agent.created · .updated · .archived · .deleted

4 4
environment

environment.created · .updated · .archived · .deleted

4 4
vault_credential

vault_credential.created · .archived · .deleted · .refresh_failed

4 4
deployment_run

deployment_run.started · .succeeded · .failed

3 3
memory_store

memory_store.created · .archived · .deleted

3 3
vault

vault.created · .archived · .deleted

3 3

All 44 events →

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.

Not affiliated with Claude Managed Agents. Facts are compiled from public sources and linked inline.