Receive and verify Anthropic Claude Managed Agents (CMA) webhooks. Use when setting up Claude Managed Agents webhook handlers, debugging signature verification, or handling agent session and vault events like session.status_idled, session.status_terminated, session.thread_created, vault.created, or vault_credential.refresh_failed.
Receive and verify Anthropic Claude Managed Agents (CMA) webhooks. Use when setting up Claude Managed Agents webhook handlers, debugging signature verification, or handling agent session and vault events like session.status_idled, session.status_terminated, session.thread_created, vault.created, or vault_credential.refresh_failed.
Handling agent session state changes (session.status_idled, session.status_terminated)
Reacting to multiagent thread events (session.thread_created, session.thread_idled)
Processing vault and credential events (vault.created, vault_credential.refresh_failed)
Replacing long-poll loops on the Sessions API with push notifications
Essential Code (USE THIS)
CMA webhooks follow the Standard Webhooks spec. Every delivery carries three headers — webhook-id, webhook-timestamp, and webhook-signature — and is signed with HMAC-SHA256 over . The signing secret is the -prefixed value shown once at endpoint creation. The Anthropic SDK exposes which wraps the same verification. Manual verification is shown here because it works in every framework without an extra SDK dependency.
If you already use the Anthropic SDK, replace the manual verification with client.beta.webhooks.unwrap(). The SDK reads ANTHROPIC_WEBHOOK_SIGNING_KEY from the environment, verifies the signature, rejects payloads older than five minutes, and parses the event:
importAnthropicfrom"@anthropic-ai/sdk";
const client = newAnthropic();
// inside your handler, after reading the raw body:const event = client.beta.webhooks.unwrap(rawBody, { headers });
import anthropic
client = anthropic.Anthropic() # requires: pip install "anthropic[webhooks]"# inside your handler, after reading the raw body:
event = client.beta.webhooks.unwrap(raw_body, headers=dict(request.headers))
CMA webhooks deliver only the event type and id — fetch the full object via the API (client.beta.sessions.retrieve(event.data.id)). The event type lives under event.data.type; the top-level event.type is always "event".
Session events
Event
Description
session.status_run_started
Agent execution started; fires on every transition to running.
session.status_idled
Agent is awaiting input (tool approval, new user message).
session.status_rescheduled
Transient error; the session is retrying automatically.
session.status_terminated
Session hit a terminal error.
session.thread_created
A new multiagent thread was opened by the coordinator.
session.thread_idled
A multiagent thread is awaiting input.
session.thread_terminated
A multiagent thread was archived.
session.outcome_evaluation_ended
Outcome evaluation finished for a single iteration.
Vault events
Event
Description
vault.created
Vault successfully created.
vault.archived
Vault archived (also emits vault_credential.archived per credential).
vault.deleted
Vault deleted (also emits vault_credential.deleted per credential).
ANTHROPIC_WEBHOOK_SIGNING_KEY=whsec_xxxxx # 32-byte whsec_-prefixed secret from Console
ANTHROPIC_API_KEY=sk-ant-xxxxx # Required if you fetch the full object via the SDK
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
Idempotency — Use the top-level event.id to deduplicate retries
Error handling — Return codes, logging, dead letter queues
Retry logic — Anthropic retries at least once; 3xx counts as a failure
Related Skills
openai-webhooks - OpenAI Standard Webhooks for fine-tuning, batch, and realtime events
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
