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

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

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](/webhooks/claude-managed-agents) overview, every event type is on [Claude Managed Agents webhook events](/webhooks/claude-managed-agents/events), and signature verification code is on [Verify Claude Managed Agents webhooks](/webhooks/claude-managed-agents/verify).

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](/webhooks/guides/webhooks-ai-agents-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](#other-limits).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Verify, enqueue and return a 2xx; fetch the resource in a worker | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Record the top-level event `id`; make handlers idempotent | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Drive state from the resource you fetch, not from arrival order | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#retries) | Never redirect; reconcile through the API; re-enable a disabled endpoint | Accepts deliveries while your service is down and replays them |
| [Choosing events](#choosing-events) | Subscribe to the types you act on, before you need them | Filters and routes events by type |
| [Testing](#testing) | Forward events to localhost through a public URL | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Plan for thin payloads, beta status, secret handling and the separate Claude Code trigger | Deduplicates upstream events before they start a Claude Code session |

## Claude Managed Agents webhook timeouts and slow handlers {#timeouts}

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](/webhooks/guides/why-implement-asynchronous-processing-webhooks). This shape is usually all a consumer needs, as [most webhook-triggered agents don't need a workflow engine](/webhooks/platforms/most-webhook-agents-dont-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](/webhooks/guides/what-are-thin-events).
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 {#duplicates}

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](/webhooks/guides/implement-webhook-idempotency), using unique constraints, upserts or natural keys rather than inserts.

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) 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 {#ordering}

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](/webhooks/guides/webhook-ordering-why-its-hard-and-how-to-handle-it) 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 {#retries}

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 {#choosing-events}

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 {#testing}

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](/webhooks/claude-managed-agents/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](/docs/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](/webhooks/platforms/how-to-test-and-replay-claude-webhooks-locally) for a walk-through.

## Other Claude Managed Agents webhook limits {#other-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](/webhooks/platforms/github-trigger-dev-claude-automation).

**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](/docs/use-cases/ai-agents) covers the full setup, including delivery timeouts and concurrency limits for the workloads that consume these events.