Claude Platform Docs
Managed Agentsエージェントに作業を委任

Webhookをサブスクライブする

ポーリングせずに、主要なイベントが発生したときに通知を受け取ります。

セッションは長時間実行されるインタラクションです。ほとんどのリアルタイムのインタラクションはSSEイベントストリームを通じて行われますが、「webhook」（Webhook）は主要な状態変化を通知します。

Webhookイベントは、オブジェクト全体ではなく、イベントのtypeとidを返します。Webhookイベントを受信したら、GET呼び出しでオブジェクトを直接取得する必要があります。これにより、リトライ時に古いデータが配信されることを防ぎ、すべての配信を小さく保つことができます。

サポートされているイベントタイプ

これらのイベントの一部は、セッションのイベントストリーム上の対応するイベントとは異なる名前が付けられています。たとえば、ストリームのsession.status_idleとsession.status_runningは、それぞれsession.status_idledとsession.status_run_startedのWebhookイベントに対応します。

イベントトリガー
session.status_run_startedエージェントの実行が開始されました。セッションのステータスがrunningに遷移するたびにトリガーされます。
session.status_idledエージェントが入力を待っています。たとえば、ツールの権限承認や新しいユーザーメッセージなどです。
session.budget_reachedセッションが予算に達し、一時停止しました。設定した予算値ごとに最大1回発生します。予算を変更すると再び有効になります。
session.status_rescheduled一時的なエラーが発生し、セッションが自動的にリトライしています。
session.status_terminated回復不能なエラー、またはアーカイブされたことにより、セッションが終了しました。
session.thread_created新しいマルチエージェントスレッドが開かれました。セッションが実行するエージェントによって呼び出された追加のエージェントが作業を開始しているか、セッションのアドバイザーに相談が行われています。また、ワークフロー実行の各スレッドに対しても発生し、この表の他の2つのスレッドイベントも同様です。
session.thread_idledマルチエージェントインタラクション内のエージェントが入力を待っています。
session.thread_terminatedスレッドがアーカイブされたか、リトライを使い果たしたことにより、マルチエージェントスレッドが終了しました。作業を完了したサブエージェントはterminatedではなくidleになります（アドバイザースレッドは相談が完了すると終了し、ワークフロー実行のスレッドは実行の終了までにサーバーがアーカイブした時点で終了します）。子スレッドに対してのみ発生します。プライマリスレッドの終了（セッション全体のアーカイブを含む）は、session.status_terminatedとしてのみ通知されます。
session.outcome_evaluation_ended単一のイテレーションに対する成果の評価が完了しました。
session.updatedセッションのプロパティが変更されました（たとえば、名前や設定が更新された場合）。
session.deletedセッションが完全に削除されました。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。

エンドポイントを登録する

Claude Consoleで、Webhooksページ（platform.claude.com/settings/workspaces/default/webhooks）に移動します。各エンドポイントは1つのワークスペースに属します。サイドバーのワークスペースピッカーで目的のワークスペースを選択してください。

Webhookエンドポイントは以下で構成されます。

  • URL： 公開的に名前解決可能なホスト名を持ち、ポート443上のHTTPSである必要があります。
  • イベントタイプ： このエンドポイントが受信するdata.type値のリストです。エンドポイントは、サブスクライブしているイベントのみを受信します。
  • 署名シークレット： 作成時に生成される、whsec_プレフィックス付きの32バイトのシークレットです。一度しか表示されないため、Webhook配信を検証するために安全に保管してください。

署名を検証する

すべての配信には、webhook-id、webhook-timestamp、webhook-signatureヘッダーが含まれます。SDKのunwrap()ヘルパーを使用すると、署名の検証とイベントの解析を1ステップで行えます。署名が無効な場合、またはペイロードが5分以上前のものである場合は例外をスローします。

ANTHROPIC_WEBHOOK_SIGNING_KEYに、エンドポイント作成時に表示されたwhsec_プレフィックス付きのシークレットを設定してください。

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # 署名が無効な場合やペイロードが古い場合、unwrap() は例外を送出します
        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":
        print("session idled:", event.data.id)
    # その他のイベントタイプを処理します

    return "", 200

イベントを処理する

本文を解析し、data.typeで分岐して、IDでリソースを取得します。確認応答として任意の2xxを返してください。それ以外のレスポンスはエンドポイントにとって不利にカウントされます。3xxはエンドポイントを即座に無効化し（リダイレクトは決して追跡されません）、その他の失敗はリトライされます。リトライと自動無効化のルールについては、配信の動作を参照してください。

すべてのイベントペイロードは同じ構造を持ち、イベントタイプ、識別子、およびイベントが発生した時刻のタイムスタンプが含まれます。

{
  "type": "event",
  "id": "whe_9d5c1f7e...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}
if event.data.type == "session.status_idled":
    session = client.beta.sessions.retrieve(event.data.id)
    notify_user(session)
return "", 204

トップレベルのevent.idは、配信ごとではなくイベントごとに一意です。同じevent.idを2回受信した場合、それはリトライであり、破棄して構いません。

配信の動作

  • 重複： エンドポイントは同じイベントを複数回受信する可能性があり、すべての試行で同じトップレベルのevent.id（webhook-idヘッダーと同じ値）が配信されます。これを使って重複を排除してください。

  • サブスクリプションの範囲： イベントは、発行された時点でそのタイプをサブスクライブしているエンドポイントにのみ配信されます。そのタイプをサブスクライブしているエンドポイントがない間に発行されたイベントは決して配信されず、後からサブスクライブしても遡って配信されることはありません。そのため、必要になる前にイベントタイプをサブスクライブしてください。

  • 順序は保証されません。 イベントは発生した順序で配信されるわけではありません。成果が先に生成された場合でも、session.status_idledがsession.outcome_evaluation_endedより先に届くことがあり、同じリソースに対する.deletedイベントが.archivedイベントより先に届くこともあります。イベントが届く順序ではなく、取得したリソースに基づいて状態を管理してください。

  • リトライ： 各エンドポイントとイベントについて、Anthropicは最大3回の配信を試行し（このセクションで後述する自動無効化をトリガーするレスポンスはリトライされません）、試行間には5秒から120秒のジッター付き指数バックオフが適用されます。すべての試行で同じevent.idが配信されます。最後の試行が失敗すると、イベントは破棄されます。後で配信するためにキューに入れられることはなく、失われたことを示すシグナルもありません。Webhookは永続的なログではないため、すべての遷移を観測する必要がある場合は、API経由でリソースを一覧表示または取得して照合してください。

  • タイムスタンプ： webhook-timestampヘッダーは配信試行が署名されたときに付与され、リトライのたびに再生成されるため、リトライがSDKの鮮度チェックで拒否されることはありません。これはイベントではなく配信試行の時刻です。イベントが発生した時刻には、イベントペイロードのcreated_atを使用してください。

  • 自動無効化： エンドポイントは、次の3つの場合に、機械可読なdisabled_reasonとともに自動的にdisabledに設定されます。

    • エンドポイントが3xxレスポンスを返した場合。リダイレクトは決して追跡されません。この場合、最初の試行でエンドポイントは即座に無効化され、理由はauto-disabled: endpoint URL returned a redirect (3xx)となります。エンドポイントが移動した場合は、ConsoleでURLを更新し、エンドポイントを再度有効にしてください。
    • Anthropicが接続する際に、エンドポイントのURLが非公開のIPアドレスに解決された場合。この場合、エンドポイントは即座に無効化され、理由はauto-disabled: endpoint URL resolved to an invalid addressとなります。
    • エンドポイントへの配信が一定期間継続して失敗した場合。理由はauto-disabled after sustained delivery failuresとなります。トリガーとなるのは配信回数ではなく、エンドポイントが途切れることなく失敗し続けている期間です。1回の2xxでこの期間はリセットされるため、1つの不安定なイベントによってエンドポイントが無効化されることはありません。

    3つのいずれも元に戻すことができます。問題を解決した後、Consoleでエンドポイントを再度有効にしてください。エンドポイントが無効化されていた間に発行されたイベントは再送されません。

Was this page helpful?