A webhook is just an HTTP POST another system sends you when something happens. Webhook-driven automation with Claude has three stages: receive the event, process it with a model call, write back the result. The model call is the easy part; reliability lives in the plumbing around it — which is your architecture to own, on any platform, since it only needs the core Messages API.
Receive: acknowledge fast, process later
Never call Claude inside the webhook handler. Source systems typically time out webhook deliveries in seconds, while a model response can take longer — and requests that would run past ten minutes need streaming or the Batch API anyway. The recommended shape:
- Verify the sender's signature (every serious webhook provider signs deliveries).
- Persist the event to a queue or table, keyed by the provider's event ID.
- Return 200 immediately. A worker consumes the queue.
Webhook providers redeliver on failure and rarely guarantee ordering, so the event ID key is your idempotency guard: if you've seen it, skip it. This mirrors how Anthropic's own webhooks (below) behave — retries carry the same event ID for deduplication, with no ordering guarantee.
Process: make the output machine-checkable
Because no human reads the intermediate output, force it into a schema with structured outputs (output_config with a JSON schema, generally available on the Claude API, Claude Platform on AWS, Bedrock, and Vertex AI; beta on Foundry). Handle the documented edge cases explicitly: a refusal returns HTTP 200 with stop_reason: "refusal" and possibly schema-invalid output, and stop_reason: "max_tokens" output may be truncated — route both to a dead-letter queue rather than writing garbage back. For transient failures, official SDKs already retry 429/5xx/connection errors with exponential backoff; anything still failing goes back on the queue with its retry count incremented.
Write back: idempotent, attributable, reversible
Writing results into the source system is ordinary integration code, with three recommended disciplines: make writes idempotent (an upsert keyed on the event ID, so a redelivered event doesn't create duplicate comments), attribute them (mark records as machine-generated, with the model ID and your trace ID), and keep them reversible where stakes are higher (write to a draft or suggestion field and let a human promote it — see human-in-the-loop design).
The inverse direction: webhooks from Claude
If you use Claude Managed Agents — Anthropic's hosted agent harness — the webhook flow also runs the other way: Anthropic POSTs to your registered HTTPS endpoint when a session changes state (for example session.status_idled or session.status_terminated), as an alternative to holding a streaming connection or polling. The documented behaviors to build against: payloads are thin (event type plus resource IDs — you fetch the resource for current state), every delivery is HMAC-signed and verifiable with the SDK's client.beta.webhooks.unwrap(), deliveries are unordered with retries reusing the same event ID, and an endpoint that fails around 20 consecutive deliveries is automatically disabled — so alert on webhook failures before that happens.
Availability caveat: Managed Agents is in beta and available only on the first-party Claude API and Claude Platform on AWS — not on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. The receive–process–write-back pattern above, by contrast, works on all platforms because the Claude call is a plain Messages request.
Choosing between the two shapes
| Situation | Shape |
|---|---|
| Single-shot transform per event (classify, summarize, draft) | Queue + Messages API call — any platform |
| Event kicks off multi-step, tool-using work | Managed Agents session; watch state via Anthropic webhooks (1P / Claude Platform on AWS, beta) |
| Events arrive in bulk and latency doesn't matter | Accumulate and process as a batch — see batch analytics |
Where to go next
The queueing backbone is covered in queue-based async processing, and the retry discipline in idempotency and retries. For scheduled rather than event-driven triggers, see scheduled agents.