Published on

Claude Managed Agents Webhooks: A Complete Guide to Long-Running AI That Wakes Your App

You handed a task to an AI agent and stepped away. Hours later you returned to find it stopped mid-work β€” it needed someone's approval, and nobody noticed.

Claude Managed Agents webhooks solve exactly that. The agent proactively notifies your app when something important happens. No waiting required.

Released alongside Dreaming, Outcomes, and multiagent orchestration in Anthropic's May 2026 Managed Agents update, this feature fundamentally changes how you run long-running AI agents in production.

Table of Contents

  1. What Are Claude Managed Agents Webhooks?
  2. The 6 Webhook Event Types
  3. Security: HMAC Signing & Replay Protection
  4. Three Real-World Usage Scenarios
  5. EdTech Perspective: The Maturity Level of AI Agent Operations

1. What Are Claude Managed Agents Webhooks?

Managed Agents is Anthropic's hosted REST API for AI agents β€” Anthropic runs the agent loop and sandbox, and your application sends events and streams back results. Unlike the Agent SDK (which runs the agent loop inside your own process), Managed Agents runs on Anthropic's infrastructure.

Webhooks are the mechanism by which these agents send HTTP callbacks to your app on significant state changes.

Old way (polling):

Your app: "Agent, done yet?" β†’ wait 5s β†’ check again β†’ wait 5s β†’ ...

Webhook way:

Agent: (task done) β†’ HTTP notification to your app β†’ your app reacts instantly

Polling wastes API calls and introduces lag. Webhooks fire at the moment events occur. The longer an agent runs, the more dramatically this difference shows.

2. The 6 Webhook Event Types

Anthropic supports the following webhook events:

EventWhen It Fires
Session startedAn agent session begins
Agent idleAgent pauses, waiting for user/operator input
Outcome evaluatedA grader model has assessed the output
Multiagent thread endedA multiagent task completes
Vault credential refresh failedA stored credential's refresh fails
Session endedAn agent session terminates

The most critical event is agent idle. It fires when the agent encounters something that requires human input or approval. Miss it and your agent hangs indefinitely.

3. Security: HMAC Signing & Replay Protection

Webhooks are inbound HTTP requests β€” security is non-negotiable. Anthropic ships several protections out of the box.

HMAC signing: Every webhook payload includes an HMAC-SHA256 signature. Your app verifies this signature to confirm the request genuinely came from Anthropic.

Replay protection: Prevents already-processed webhooks from being applied again. Safe even if the same event arrives twice due to a network hiccup.

At-least-once delivery: Anthropic guarantees each event is delivered at minimum once. If your app goes down temporarily, missed events are retried when you come back up.

SDK helpers in 7 languages: Python, TypeScript, Go, Java, Ruby, Rust, and PHP SDKs all include built-in webhook verification helpers.

from anthropic import Anthropic

client = Anthropic()

def handle_webhook(payload: bytes, signature: str):
    event = client.managed_agents.webhooks.verify(
        payload=payload,
        signature=signature
    )
    if event.type == "agent.idle":
        # Agent is waiting for input β†’ send Slack notification
        notify_slack(event.session_id)

4. Three Real-World Usage Scenarios

Scenario 1: Slack Alert When the Agent Stalls

A code review agent is analyzing a PR and encounters a security-sensitive file change. It requires human approval and fires agent.idle. Your app catches the webhook and pings the team's Slack channel β€” the right person responds quickly.

Scenario 2: Auto-Retry When Outcome Fails

The agent's output doesn't pass the Outcome rubric. The outcome.evaluated event returns passed: false. Your app automatically sends the agent a retry instruction with specific feedback from the grader.

Scenario 3: Auto-Chaining a Multiagent Pipeline

A data collection agent β†’ analysis agent β†’ report writing agent runs in sequence. Each session.ended webhook triggers the next agent automatically. No human intervention needed across the full pipeline.

5. EdTech Perspective: The Maturity Level of AI Agent Operations

Webhooks are a technical feature, but I see them as a maturity indicator for AI agent operations.

Early AI agent usage was simple: ask a question, get an answer. The next step was delegating tasks to agents. Now we're at integrating agents into existing processes.

Without webhooks, an agent is an isolated tool. With webhooks, the agent weaves into your existing workflow β€” Slack notifications, database updates, triggering the next process. That integration is what makes AI agents genuinely useful, not just impressive in demos.

In an education platform context: imagine essay grading agents, course content update agents, and learning pattern analysis agents all connected to an LMS via webhooks. AI stops being a bolt-on feature and becomes a core axis of the system.

Tips

  1. Handle agent.idle first: Setting up an alert for agent stalls is the most valuable first step. Never miss a moment when human input is needed.
  2. Always implement HMAC verification: Your webhook endpoint is open to the internet. Use the SDK helper β€” don't skip signature validation.
  3. Account for at-least-once delivery: The same event can arrive twice. Build idempotent handling logic upfront.
  4. Start with a two-step pipeline: Build Agent A β†’ webhook β†’ Agent B first. Get that working before adding complexity.

Wrapping Up

Webhooks aren't a flashy feature. But if you're serious about running AI agents in production, they're a foundational requirement.

The transition from "agents do work" to "agents integrate into your systems" is what makes AI agents actually useful. Webhooks are the wire that makes that connection real.

What scenario in your service would benefit most from AI agent webhooks? Share it in the comments!

Sources

Discuss on Twitter β€’ View on GitHub
Claude Managed Agents Webhooks: A Complete Guide to Long-Running AI That Wakes Your App | MINSSAM.COM