# 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](https://code.claude.com/docs/en/routines#add-an-api-trigger) instead. [Organization webhooks](https://platform.claude.com/docs/en/manage-claude/organization-webhooks), for enforcement actions on user profiles, are a separate API whose docs say no events are sent yet.

Agent skill: `npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks` ([details](https://hookdeck.com/webhooks/claude-managed-agents/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Claude Managed Agents's official docs](https://platform.claude.com/docs/en/managed-agents/webhooks).

[Overview](https://hookdeck.com/webhooks/claude-managed-agents) · [Webhook events (44)](https://hookdeck.com/webhooks/claude-managed-agents/events) · [MCP events](https://hookdeck.com/webhooks/claude-managed-agents/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/claude-managed-agents/verify) · [Production guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/claude-managed-agents/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `webhook-signature` Format: v1,<base64>, as a space-separated list | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Scheme | `HMAC-SHA256, base64` | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Signed material | `{webhook-id}.{webhook-timestamp}.{raw body}` The two header values and the body as sent, joined with literal dots. | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| How events are identified | `data.type field in the body` | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Body format | `JSON` Content type: application/json. | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Send timestamp | `webhook-timestamp` Reject deliveries older than 5 minutes. | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Other headers | `webhook-id, webhook-timestamp` | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Envelope | `type, id, created_at, data` | [Claude Managed Agents docs](https://platform.claude.com/docs/en/managed-agents/webhooks) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/claude-managed-agents/skill) |

[Verify Claude Managed Agents webhooks](https://hookdeck.com/webhooks/claude-managed-agents/verify)

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

## Setting up Claude Managed Agents webhooks

- Add an endpoint on the [Webhooks page](https://platform.claude.com/settings/workspaces/default/webhooks) 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

- **Timeout:** not documented. the webhooks page gives no limit, so respond as soon as you can. [Guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 3 attempts. with jittered exponential backoff between 5 and 120 seconds, all with the same `id`. [Guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** dropped. with no signal that it was lost, so reconcile by listing or fetching through the API. [Guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. a `.deleted` event can arrive before the `.archived` event. [Guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#ordering)

From [Hookdeck's Claude Managed Agents guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts).

## Claude Managed Agents webhook best practices

- **[Verify every delivery](https://hookdeck.com/webhooks/claude-managed-agents/verify).** Use `unwrap()` or a Standard Webhooks library on the raw body, when the request arrives.
- **[Return a 2xx quickly](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#duplicates).** Every attempt carries the same `id`, which matches `webhook-id`. Don't use `data.id`, because different events share it.
- **[Drive state from the resource you fetch](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#ordering).** Events can arrive in any order, so fetch current state. After a `.deleted` event there's nothing to fetch, so treat the event as final.
- **[Never answer with a redirect](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#retries).** One `3xx` disables 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](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/claude-managed-agents/events#session.status_run_started): Agent starts running, on every move into running status
- [session.status_idled](https://hookdeck.com/webhooks/claude-managed-agents/events#session.status_idled): Agent stops and waits for input, such as a tool approval
- [session.status_terminated](https://hookdeck.com/webhooks/claude-managed-agents/events#session.status_terminated): Session ends after an unrecoverable error or being archived
- [session.outcome_evaluation_ended](https://hookdeck.com/webhooks/claude-managed-agents/events#session.outcome_evaluation_ended): Outcome evaluation finishes for one iteration

### Scheduled deployments

- [deployment_run.started](https://hookdeck.com/webhooks/claude-managed-agents/events#deployment_run.started): Scheduled run starts; manual runs don't send this
- [deployment_run.failed](https://hookdeck.com/webhooks/claude-managed-agents/events#deployment_run.failed): Scheduled run fails to create a session
- [deployment.paused](https://hookdeck.com/webhooks/claude-managed-agents/events#deployment.paused): Deployment pauses on request or after an unrecoverable run failure

### Credentials and budgets

- [vault_credential.refresh_failed](https://hookdeck.com/webhooks/claude-managed-agents/events#vault_credential.refresh_failed): An MCP OAuth credential can no longer be refreshed
- [session.budget_reached](https://hookdeck.com/webhooks/claude-managed-agents/events#session.budget_reached): Session hits its spending budget and pauses

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [session](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-session) | 17 | 17 |
| [deployment](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-deployment) | 6 | 6 |
| [agent](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-agent) | 4 | 4 |
| [environment](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-environment) | 4 | 4 |
| [vault_credential](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-vault-credential) | 4 | 4 |
| [deployment_run](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-deployment-run) | 3 | 3 |
| [memory_store](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-memory-store) | 3 | 3 |
| [vault](https://hookdeck.com/webhooks/claude-managed-agents/events#resource-vault) | 3 | 3 |

[All 44 events](https://hookdeck.com/webhooks/claude-managed-agents/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/claude-managed-agents/events): Every covered Claude Managed Agents event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/claude-managed-agents/mcp-events): How an agent subscribes to Claude Managed Agents events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/claude-managed-agents/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/claude-managed-agents/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/claude-managed-agents/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks`
---

Not affiliated with Claude Managed Agents. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/claude-managed-agents.json) · [Report a correction](https://hookdeck.com/contact)
