Claude Managed Agents webhooks in production: duplicates, ordering, retries and timeouts

Published · Updated

This guide covers the problems Claude Managed Agents webhooks cause in production and how to handle each one. What Anthropic sends and how it's signed is on the Claude Managed Agents webhooks overview, every event type is on Claude Managed Agents webhook events, and signature verification code is on Verify Claude Managed Agents webhooks.

These are the events Anthropic sends to your endpoint about agent sessions and the resources around them. In the terms of our map of webhook and AI agent integration patterns, they are completion callbacks: events arriving back from asynchronous AI work. Starting Claude Code from another system's webhook runs the other way, and is covered under other limits.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsVerify, enqueue and return a 2xx; fetch the resource in a workerAccepts the delivery at once, then queues it for your service
DuplicatesRecord the top-level event id; make handlers idempotentDrops repeats before they reach your handler
OrderingDrive state from the resource you fetch, not from arrival orderLogs every event and attempt, so you can see arrival order when debugging
RetriesNever redirect; reconcile through the API; re-enable a disabled endpointAccepts deliveries while your service is down and replays them
Choosing eventsSubscribe to the types you act on, before you need themFilters and routes events by type
TestingForward events to localhost through a public URLForwards to localhost and replays past events
Other limitsPlan for thin payloads, beta status, secret handling and the separate Claude Code triggerDeduplicates upstream events before they start a Claude Code session

Claude Managed Agents webhook timeouts and slow handlers

Return a 2xx as soon as you've verified the event, then do the work in a background job.

Why it happens: Any response other than a 2xx counts against the endpoint. Anthropic's Managed Agents docs give no time limit for that response, so don't assume a slow handler has long. Its separate organization webhooks allow 5 seconds. Payloads carry ids rather than objects, so a handler that fetches the resource before responding adds an API round trip to every delivery.

Fix it in your handler:

  1. Verify the signature, push the event onto a queue and return a 2xx. See why to process webhooks asynchronously. This shape is usually all a consumer needs, as most webhook-triggered agents don't need a workflow engine explains.
  2. Verify when the request arrives, before the event reaches your queue. The SDK's unwrap() rejects a payload more than 5 minutes old, so a worker that verifies behind a backlog rejects real events. Retries aren't affected, because Anthropic stamps webhook-timestamp afresh on each attempt.
  3. Fetch the resource in the worker, and cache it by id if the same session is likely to arrive several times in quick succession. See what thin events are.
  4. Skip the fetch when the event type is enough to act on. .deleted events always need this, because there's no object left to fetch.

With Event Gateway: Hookdeck accepts each delivery immediately, verifies the signature, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your worker can fetch the full resource at its own pace.

Duplicate Claude Managed Agents webhooks

An endpoint can receive the same event more than once. Record the top-level event id you process and skip repeats.

Why it happens: Anthropic retries failed deliveries, and every attempt carries the same id, which is also the value of the webhook-id header. Each event keeps one id however many deliveries it takes, which makes it usable as an idempotency key. If your handler finishes the work and then fails to respond, the retry repeats that work.

Fix it in your handler:

  1. Track processed id values in a fast key-value store with a TTL longer than the retry window, or in a table with a unique constraint.
  2. Don't deduplicate on data.id. It identifies the resource, so different events share it: deployment_run.started and deployment_run.succeeded carry the same run ID.
  3. Make every side effect idempotent, using unique constraints, upserts or natural keys rather than inserts.

With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

Out-of-order Claude Managed Agents webhooks

Anthropic doesn't guarantee delivery order. Drive your state from the resource you fetch, not from the order events arrive in.

Why it happens: session.status_idled can arrive before session.outcome_evaluation_ended even when the outcome was produced first, and a .deleted event can arrive before the .archived event for the same resource. A state machine that assumes sequential delivery ends up in impossible states.

Fix it in your handler:

  1. Treat each event as a prompt to fetch the current state from the API, rather than as the state itself.
  2. Read created_at from the body for when the event occurred. webhook-timestamp is the clock for the delivery attempt, and it changes on every retry.
  3. Let a .deleted event win over any later .archived event for the same resource.

See why webhook ordering is hard for more on these patterns.

With Event Gateway: Hookdeck logs every event and delivery attempt, so you can see the order things arrived in when debugging, and replay events during recovery. Your handler still decides what to do with an out-of-order event.

Claude Managed Agents webhook retries and disabled endpoints

Anthropic makes up to three delivery attempts, then drops the event. Three conditions disable the endpoint, and events emitted while it's disabled are never replayed.

Why it happens: Attempts are spaced by jittered exponential backoff between 5 and 120 seconds, so three attempts can run out during a short deploy. After the last one, the event isn't queued and there's no signal that it was lost. An endpoint is set to disabled, with a machine-readable disabled_reason, when:

  • It returns a 3xx. Anthropic never follows redirects, so this disables it on the first attempt, with no retry.
  • Its URL resolves to a non-public IP address when Anthropic connects.
  • Deliveries fail continuously for a sustained period. The trigger is how long the endpoint has been failing, not a delivery count, and Anthropic gives no figure for it. A single 2xx resets the window, so one event that fails intermittently can't disable the endpoint.

Fix it in your handler:

  1. Reconcile by listing or fetching resources through the API on a schedule, and after any outage. Webhooks aren't a durable log.
  2. Never put the endpoint behind a redirect. If it moves, add a new endpoint with the new URL and the same event types, delete the old one, and update ANTHROPIC_WEBHOOK_SIGNING_KEY, because the new endpoint has its own secret.
  3. Re-enable a disabled endpoint in the Console once you've fixed the cause, then reconcile what you missed. Alert on a gap in deliveries, so you notice before the next outage.
  4. Return a 2xx once you've accepted an event, and handle application errors in your worker, so a bug in one handler doesn't count against the endpoint.

With Event Gateway: Hookdeck accepts deliveries while your service is down and replays them when it recovers. Anthropic only sees Hookdeck's response, so a failing service doesn't use up its attempts or count toward disabling the endpoint. Hookdeck's URL also stays the same when your application's hostname changes, so a move is a routing change in Hookdeck rather than a new endpoint in the Console.

Choosing which Claude Managed Agents events to listen to

Subscribe each endpoint to the event types you act on, and do it before you need them.

Why it happens: An endpoint receives only the types it's subscribed to. An event emitted while no endpoint subscribes to its type is never delivered, and subscribing later doesn't backfill it. Subscribing to everything has its own cost, because your handler then has to filter events it never needed.

Fix it in your handler:

  1. Start from the events that need a person or a follow-up: session.status_idled, session.status_terminated, session.budget_reached, vault_credential.refresh_failed, deployment.paused and deployment_run.failed. A scheduled run that fails with an unrecoverable error pauses its deployment, so deployment.paused is worth an alert.
  2. Switch on data.type. The top-level type is always event.
  3. Read deployment_run.succeeded carefully. It means the run created its session, so follow the session's events to learn how its work went. Manual runs send no deployment_run events at all.
  4. Use session.status_terminated for the end of a whole session. session.thread_terminated fires for child threads only.
  5. Use the webhook names, which differ from the session's event stream: the stream's session.status_idle is the webhook's session.status_idled.
  6. Prefer the events on Anthropic's webhooks page. The API reference also lists session.created, session.pending, session.running, session.idled, session.requires_action and session.archived, with no description of when they fire.

With Event Gateway: Hookdeck can filter events and route them to different destinations by data.type, so you can subscribe once and send each type where it belongs.

Testing and debugging Claude Managed Agents webhooks locally

Forward real events to your local server through a public URL rather than deploying to test.

Why it happens: An endpoint's URL must be HTTPS on port 443 with a publicly resolvable hostname, and one that resolves to a non-public IP address gets disabled. Anthropic's docs describe no CLI for forwarding events and no way to resend one, so you trigger an event by doing the thing it reports, such as starting a session.

How to test:

  1. Run a tunnel or a forwarding tool to get a public URL for your local server, and add it as a separate endpoint with its own signing secret.
  2. Save real payloads as fixtures, and start from the samples on Claude Managed Agents webhook events. Anthropic publishes one full example, so most of those samples are built from its API reference.
  3. Test signature verification with the real signing secret in every environment, not only locally.

With Event Gateway: The Hookdeck CLI gives you a stable URL that sends webhooks to your machine: run hookdeck listen 3000 claude-managed-agents --path /webhooks/claude-managed-agents, then replay past events with one click. See how to test and replay Claude webhooks locally for a walk-through.

Other Claude Managed Agents webhook limits

Thin payloads. Every event carries ids rather than the object, which avoids delivering stale data on retries and keeps deliveries small. Budget for the extra API calls under high volume, and queue them.

New event types. Anthropic has added event families since webhooks launched, including deployments, environments and memory stores. Log and acknowledge any data.type your handler doesn't recognise rather than failing on it.

Signing secrets. The secret is shown only once, when you create the endpoint, so store it in a secrets manager or an environment variable. The Managed Agents docs describe no way to rotate it on an existing endpoint.

Beta and data handling. Webhooks are in beta on every model. Anthropic lists Managed Agents as not eligible for zero data retention or HIPAA.

Starting Claude Code from a webhook. This runs the other way and is a separate product. You POST to a routine's endpoint, /v1/claude_code/routines/{routine_id}/fire, which Claude Code's docs now describe as an API trigger on a scheduled task. Each successful request creates a new session and there's no idempotency key, so a caller that retries creates more sessions. Each routine accepts up to 30 fires per hour and each account up to 100 API fires per hour. Deduplicate on the upstream provider's event ID before you call it, as in our walk-through of GitHub, Trigger.dev and Claude.

Organization webhooks. Anthropic's Admin API has a separate webhook surface for enforcement actions on user profiles. Its docs say event delivery isn't live yet, and it isn't part of these pages.

With Event Gateway: Hookdeck can sit in front of the Claude Code trigger too, and drop a repeated upstream event before it starts a second session. The AI Agents & LLMs use case covers the full setup, including delivery timeouts and concurrency limits for the workloads that consume these events.

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.