【速報】Claude Managed Agents の Webhooks 機能を試してみた

こんにちは、せーのです。今朝の朝方、サンフランシスコで開催された Code with Claude developers' conference で、Claude Managed Agents 向けに Webhooks が Public Beta として発表されました。Dreaming や Outcomes、Multiagent など目立つ話題と一緒に並んでいましたが、業務に組み込むならここが地味に効く、というタイプのアップデートです。

今日は公式ブログとドキュメントベースで、何ができるようになったかと実装するときの落とし穴を整理し、末尾で手元検証の結果も書きます。手

Managed Agents の文脈で Webhooks が意味すること

Claude Managed Agents は、クラウド上で長めのタスクを回すための仕組みです。セッションの進み具合は、これまでも SSE のイベントストリームでリアルタイムに追えました。

一方で「ジョブが終わったら Slack に飛ばしたい」「完了したら別サービスを叩きたい」といった サーバー同士の連携では、クライアントが常にストリームを張りっぱなしにするのは不向きなこともあります。今回の Webhooks は、そのギャップを埋めるための プッシュ通知です。Console から HTTPS エンドポイントを登録し、選んだイベント種別が起きたときに Anthropic 側から POST されます。

今回の Beta でできること（要点）

• 設定場所: Claude Console の Manage > Webhooks（ワークスペース単位）。
• URL 条件: HTTPS・ポート 443・公開解決可能なホスト名（ローカル検証なら ngrok 等が定番です）。
• Signing secret: 登録時に whsec_ で始まるシークレットが一度だけ表示されます。環境変数 ANTHROPIC_WEBHOOK_SIGNING_KEY に載せて SDK の検証に使います。
• イベントの粒度: 大きく セッションまわりと Vault / クレデンシャルまわりに分かれます。

代表的なセッション系イベントだけ挙げると次のとおりです。Multiagent や Outcomes を使っている場合は、スレッドや評価イテレーション用のイベントも選べます。

Vault 側は vault.created や vault_credential.refresh_failed（OAuth リフレッシュ失敗）など、運用で効いてきそうなものが並びます。全種の表は 公式ドキュメント: Subscribe to webhooks に任せます。

設計のコツ：ペイロードは ID のみ、詳細は GET

公式の設計方針ははっきりしていて、Webhook の本文にはフルオブジェクトを載せない代わりに type と id 中心で届きます。受け取った側で sessions.retrieve など GET で最新状態を取りに行く想定です。リトライで古いスナップショットが再送される、といった事故を避けやすくするためだと読めます。

イメージとしては次のような形です（値はすべてダミーです）。

{
  "type": "event",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

配信まわりも「本番で詰まりやすいところ」が先に書いてあります。

冪等性は event.id をキーにして二重処理を防ぐのが定石です。開発中はメモリの set でもよいですが、本番では Redis のような永続ストアを検討する、とドキュメント側も同じ方向を指しています。

署名検証と実装時の落とし穴

すべての配信に X-Webhook-Signature が付きます。Python / TypeScript SDK とも client.beta.webhooks.unwrap(...) で署名検証とパースを一度に済ませられます。署名が不正、または時刻が古すぎる（ドキュメント上は 5 分超）と例外になります。

ここで一番ハマりやすいのが Express で express.json() を先に噛ませてしまうパターンです。署名は 生のボディバイトで計算されるので、JSON パース済みの文字列を渡すと検証がズレます。express.raw({ type: "application/json" }) でルートを切る、と公式例でも強調されています。Flask 側は request.get_data(as_text=True) のように素のボディを渡す形です。

Python の最小イメージは次のとおりです（API キーは載せていません）。

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()
app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.data.type == "session.status_idled":
        session = client.beta.sessions.retrieve(event.data.id)
        # session を使って通知処理など
        _ = session

    return "", 204

SSE ストリームとの使い分け

公式の整理を借りると、用途ごとの推奨はだいたい次のイメージです。

違いを整理すると、ストリームは「観測用のライブ映像」、Webhookは「後段処理のためのベル」、というイメージです。併用ももちろんありです。

やってみた

結論から言うと、Anthropic から Webhook が 1 件も届きませんでした。 。設定を色々調べましたが、間違ってはいないようです。

やったことの骨子だけ書くと、ngrok で 127.0.0.1:8000 を HTTPS 公開し、Console にエンドポイントを登録し、GitHub 版の Python SDK と anthropic[webhooks] で unwrap() 付きの Flask サーバーを立て、Managed Agents のセッションを走らせて session.status_idle まで到達させました。イベントの流れは API 上ではきちんと追えています。ところが ngrok の受信ログを見る限り、Anthropic からの POST はゼロ件でした。URL・署名用シークレット・到達性まわりは手元では一通り確認済みです。

詳しい手順、SDK のバージョンの話、ngrok で IPv6 にハマった話などは claude-webhooks/hands-on.md に書いてありますので、そちらを参照ください（ペイロードの実例は、届かなかったので載せられていません）。

発表の翌日に試したというタイミングもあり、まだ配信まわりが不安定なのではないか、という印象です。同様に「届かない」という報告が claude-cookbooks の issue #539 にもあり、単なる設定ミスではないようです。一方で SSE（イベントの列挙・ストリーム）側は問題なく動いており、「セッションは idle まで行っているのにベルが鳴らない」という状態でした。

落ち着いて配信が安定したら、できることは多そうです。長時間セッションの完了をポーリングなしで拾って Slack やメールに流す、Human-in-the-loop の承認待ちを別システムのキューに載せる、CI の結果をトリガーにしたエージェントが終わったら次のジョブを起動する、といった イベント駆動のバックエンドに Webhook が乗るはずです。公式が描いている「ストリームで観測、Webhook で連携」の分業が、実機でも当たり前になるのを待ちたいところです。しばらくしたら同じ手順でもう一度だけ試してみます。

まとめ

• Claude Managed Agents に Webhooks が来たので、セッションや Vault の状態変化を ポーリングなしで受け取れる設計になった（Public Beta）。手元検証では 配信自体は未確認で、現時点では SSE が確実に使える手段という整理が現実的です。
• ペイロードは ID 中心なので、届いたあと 必ず API で最新状態を GET する前提で設計する。
• 署名検証は raw ボディ、event.id で冪等、順序は保証されない、の三点セットを最初にコードに落とし込むと安全。
• リアルタイム観測は SSE、外部連携・通知は Webhook（配信が安定したら）、と役割を分けると迷いにくいです。

配信が安定したら、このセクションを差し替えて実ペイロード付きでまた書き直すかもしれません。

参考資料

• New in Claude Managed Agents（公式ブログ）
• Subscribe to webhooks（公式ドキュメント）
• Console: Webhooks 設定
• Code with Claude Keynote（YouTube）
• Claude @ X（告知ポスト例）