--- title: Webhookをサブスクライブする url: https://platform.claude.com/docs/ja/managed-agents/webhooks description: ポーリングせずに、主要なイベントが発生したときに通知を受け取ります。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- セッションは長時間実行されるインタラクションです。ほとんどのリアルタイムのインタラクションは[SSEイベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)を通じて行われますが、「webhook」（Webhook）は主要な状態変化を通知します。 Webhookイベントは、オブジェクト全体ではなく、イベントの`type`と`id`を返します。Webhookイベントを受信したら、`GET`呼び出しでオブジェクトを直接取得する必要があります。これにより、リトライ時に古いデータが配信されることを防ぎ、すべての配信を小さく保つことができます。 ## サポートされているイベントタイプ これらのイベントの一部は、セッションの[イベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)上の対応するイベントとは異なる名前が付けられています。たとえば、ストリームの`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` | セッションが[予算](https://platform.claude.com/docs/ja/managed-agents/budgets)に達し、一時停止しました。設定した予算値ごとに最大1回発生します。予算を変更すると再び有効になります。 | | `session.status_rescheduled` | 一時的なエラーが発生し、セッションが自動的にリトライしています。 | | `session.status_terminated` | 回復不能なエラー、またはアーカイブされたことにより、セッションが終了しました。 | | `session.thread_created` | 新しい[マルチエージェントスレッド](https://platform.claude.com/docs/ja/managed-agents/session-threads)が開かれました。セッションが実行するエージェントによって呼び出された追加のエージェントが作業を開始しているか、セッションの[アドバイザー](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#give-the-session-an-advisor)に相談が行われています。また、[ワークフロー実行](https://platform.claude.com/docs/ja/managed-agents/workflow-runs#a-runs-threads)の各スレッドに対しても発生し、この表の他の2つのスレッドイベントも同様です。 | | `session.thread_idled` | [マルチエージェントインタラクション](https://platform.claude.com/docs/ja/managed-agents/session-threads)内のエージェントが入力を待っています。 | | `session.thread_terminated` | スレッドがアーカイブされたか、リトライを使い果たしたことにより、[マルチエージェントスレッド](https://platform.claude.com/docs/ja/managed-agents/session-threads)が終了しました。作業を完了したサブエージェントは`terminated`ではなく`idle`になります（アドバイザースレッドは相談が完了すると終了し、ワークフロー実行のスレッドは実行の終了までにサーバーがアーカイブした時点で終了します）。子スレッドに対してのみ発生します。プライマリスレッドの終了（セッション全体のアーカイブを含む）は、`session.status_terminated`としてのみ通知されます。 | | `session.outcome_evaluation_ended` | 単一のイテレーションに対する[成果の評価](https://platform.claude.com/docs/ja/managed-agents/define-outcomes)が完了しました。 | | `session.updated` | セッションのプロパティが変更されました（たとえば、名前や設定が更新された場合）。 | | `session.deleted` | セッションが完全に削除されました。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | | イベント | トリガー | | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `vault.created` | Vaultが作成されました。 | | `vault.archived` | Vaultがアーカイブされました。基盤となる各認証情報に対して`vault_credential.archived`イベントも発行されます。 | | `vault.deleted` | Vaultが削除されました。基盤となる各認証情報に対して`vault_credential.deleted`イベントも発行されます。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | | `vault_credential.created` | 認証情報が作成されました。 | | `vault_credential.archived` | 認証情報が、直接またはVaultのアーカイブの結果としてアーカイブされました。 | | `vault_credential.deleted` | 認証情報が、直接またはVaultの削除の結果として削除されました。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | | `vault_credential.refresh_failed` | `mcp_oauth`認証情報を更新できません（無効なリフレッシュトークン、またはOAuthサーバーからの回復不能なエラー）。 | これらのイベントはワークスペース内のエージェントリソースのライフサイクルを追跡するもので、セッションのイベントストリームで配信されるエージェントイベントとは異なります。 | イベント | トリガー | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.created` | エージェントが作成されました。 | | `agent.updated` | [エージェントの新しいバージョン](https://platform.claude.com/docs/ja/managed-agents/agent-setup#update-an-agent)が公開されました。新しいバージョンを作成しない更新では、このイベントはトリガーされません。 | | `agent.archived` | エージェントがアーカイブされました。 | | `agent.deleted` | エージェントが完全に削除されました。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | | イベント | トリガー | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `deployment.created` | [スケジュールされたデプロイメント](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments)が作成されました。 | | `deployment.updated` | デプロイメントのプロパティが変更されました（たとえば、スケジュールが更新された場合）。 | | `deployment.paused` | デプロイメントが、リクエストによって、またはスケジュールされた実行がアーカイブされたサブエージェントやアーカイブされた環境などの回復不能なエラーで失敗したときに自動的に、一時停止されました。レート制限を含む回復可能な失敗では、デプロイメントは一時停止されません。[失敗時の動作](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments#failure-behavior)を参照してください。 | | `deployment.unpaused` | デプロイメントの一時停止が解除され、スケジュールが再開されました。 | | `deployment.archived` | デプロイメントが、直接またはそのエージェントがアーカイブされたことによりアーカイブされました。代わりにエージェントが削除された場合、スケジュールされたデプロイメントは次回のスケジュール実行時にアーカイブされます。スケジュールのないデプロイメントは自動的にはアーカイブされません。 | | `deployment.deleted` | デプロイメントが完全に削除されました。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | | イベント | トリガー | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment_run.started` | スケジュールされた実行が開始されました。`deployment_run`イベントを発行するのはスケジュールされた実行のみで、[手動実行](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments#trigger-a-manual-run)では発行されません。 | | `deployment_run.succeeded` | スケジュールされた実行がセッションを作成しました。このイベントは、その実行の`deployment_run.started`イベントと同じ`data.id`（実行ID）を持ちます。セッションの作業を追跡するには、そのセッションイベント（セッションイベントタブ）をサブスクライブするか、[デプロイメント実行](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments#deployment-runs)を取得してその`session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`)を確認してください。 | | `deployment_run.failed` | スケジュールされた実行がセッションを作成しませんでした。このイベントは、その実行の`deployment_run.started`イベントと同じ`data.id`を持ちます。エラーの詳細については、[デプロイメント実行](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments#deployment-runs)を取得してください。 | | イベント | トリガー | | ---------------------- | ----------------------------------------------------------------------------- | | `environment.created` | 環境が作成されました。 | | `environment.updated` | 少なくとも1つのフィールドが変更されて環境が更新されました。何も変更しない更新では何も発行されません。 | | `environment.archived` | 環境がアーカイブされました。すでにアーカイブされた環境を再度アーカイブしても何も発行されません。 | | `environment.deleted` | 環境が削除されました（すでにアーカイブされた環境の削除を含む）。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | 環境の[ワークアイテム](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes)はWebhookイベントを発行しません。 | イベント | トリガー | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `memory_store.created` | メモリストアが、ユーザー自身によって、または既存のストアのいずれかを複製するAnthropicが運用するプロセスによって作成されました。 | | `memory_store.archived` | メモリストアがアーカイブされました。すでにアーカイブされたストアを再度アーカイブしても何も発行されません。 | | `memory_store.deleted` | メモリストアが削除されました（すでにアーカイブされたストアの削除を含む）。ストアを削除すると、そのメモリとメモリバージョンもカスケード削除されますが、メモリごとのイベントは発行されません。単一の`memory_store.deleted`イベントがそのシグナルとなります。取得できるオブジェクトは残っていないため、イベント自体を最終的なものとして扱ってください。 | 個々の[メモリ](https://platform.claude.com/docs/ja/managed-agents/memory)およびメモリバージョンはWebhookイベントを発行しません。 ## エンドポイントを登録する Claude Consoleで、[Webhooks](https://platform.claude.com/settings/workspaces/default/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()` (csharp, go: `Unwrap()`)ヘルパーを使用すると、署名の検証とイベントの解析を1ステップで行えます。署名が無効な場合、またはペイロードが5分以上前のものである場合は例外をスローします。 `ANTHROPIC_WEBHOOK_SIGNING_KEY`に、エンドポイント作成時に表示された`whsec_`プレフィックス付きのシークレットを設定してください。 ```python Python 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 ``` ```typescript TypeScript import express from "express"; import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env const app = express(); // 重要: express.json() ではなく express.raw() を使用してください。署名は生のバイト列に対して計算されます。 app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { let event; try { // 署名が無効な場合やペイロードが古い場合、unwrap() は例外をスローします event = client.beta.webhooks.unwrap(req.body.toString("utf8"), { headers: req.headers as Record }); } catch { return res.status(400).send("invalid signature"); } switch (event.data.type) { case "session.status_idled": console.log("session idled:", event.data.id); break; // その他のイベントタイプを処理します } res.sendStatus(200); }); ``` ```csharp C# using Anthropic; var client = new AnthropicClient(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env var app = WebApplication.Create(args); app.MapPost("/webhook", async (HttpRequest request) => { using var reader = new StreamReader(request.Body); var body = await reader.ReadToEndAsync(); var headers = request.Headers.ToDictionary(header => header.Key, header => header.Value.ToString()); UnwrapWebhookEvent webhookEvent; try { // 署名が無効な場合、またはペイロードが古い場合、Unwrap() は例外をスローします webhookEvent = client.Beta.Webhooks.Unwrap(body, headers); } catch { return Results.BadRequest("invalid signature"); } if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled)) { Console.WriteLine($"session idled: {idled.ID}"); } // その他のイベントタイプを処理します return Results.Ok(); }); ``` ```go Go package main import ( "fmt" "io" "net/http" "github.com/anthropics/anthropic-sdk-go" ) var client = anthropic.NewClient() // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env func webhook(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "could not read body", http.StatusBadRequest) return } // 署名が無効な場合、またはペイロードが古い場合、Unwrap はエラーを返します event, err := client.Beta.Webhooks.Unwrap(body, r.Header) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } switch event.Data.Type { case "session.status_idled": fmt.Println("session idled:", event.Data.ID) // その他のイベントタイプを処理します } w.WriteHeader(http.StatusOK) } func main() { http.HandleFunc("/webhook", webhook) } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.UnwrapWebhookParams; import com.anthropic.core.http.Headers; import com.sun.net.httpserver.HttpServer; // 環境変数から ANTHROPIC_WEBHOOK_SIGNING_KEY を読み取ります AnthropicClient client = AnthropicOkHttpClient.fromEnv(); void main() throws Exception { var server = HttpServer.create(new InetSocketAddress(8000), 0); server.createContext("/webhook", exchange -> { var body = new String(exchange.getRequestBody().readAllBytes()); var headers = Headers.builder(); exchange.getRequestHeaders().forEach(headers::put); try { // 署名が無効な場合やペイロードが古い場合、unwrap() は例外をスローします var event = client.beta().webhooks().unwrap( UnwrapWebhookParams.builder() .body(body) .headers(headers.build()) .build()); event.data().sessionStatusIdled().ifPresent(idled -> IO.println("session idled: " + idled.id())); // その他のイベントタイプを処理します exchange.sendResponseHeaders(200, -1); } catch (Exception _) { exchange.sendResponseHeaders(400, -1); } exchange.close(); }); } ``` ```php PHP use Anthropic\Client; use Anthropic\Core\Exceptions\WebhookException; $client = new Client(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env $body = file_get_contents('php://input'); $headers = getallheaders(); try { // 署名が無効な場合やペイロードが古い場合、unwrap() は例外をスローします $event = $client->beta->webhooks->unwrap($body, headers: $headers); } catch (WebhookException) { http_response_code(400); exit('invalid signature'); } match ($event->data->type) { 'session.status_idled' => print "session idled: {$event->data->id}\n", // その他のイベントタイプを処理します default => null, }; http_response_code(200); ``` ```ruby Ruby require "sinatra" require "anthropic" client = Anthropic::Client.new # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env post "/webhook" do headers = request.env .select { |key, _| key.start_with?("HTTP_") } .transform_keys { it.delete_prefix("HTTP_").downcase.tr("_", "-") } begin # 署名が無効な場合やペイロードが古い場合、unwrap は例外を送出します event = client.beta.webhooks.unwrap(request.body.read, headers: headers) rescue StandardError halt 400, "invalid signature" end if event.data.type == :"session.status_idled" puts "session idled: #{event.data.id}" end # その他のイベントタイプを処理します status 200 end ``` ## イベントを処理する 本文を解析し、`data.type`で分岐して、IDでリソースを取得します。確認応答として任意の`2xx`を返してください。それ以外のレスポンスはエンドポイントにとって不利にカウントされます。`3xx`はエンドポイントを即座に無効化し（リダイレクトは決して追跡されません）、その他の失敗はリトライされます。リトライと自動無効化のルールについては、[配信の動作](https://platform.claude.com/docs/ja/managed-agents/webhooks#delivery-behavior)を参照してください。 すべてのイベントペイロードは同じ構造を持ち、イベントタイプ、識別子、およびイベントが発生した時刻のタイムスタンプが含まれます。 ```json { "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-..." } } ``` ```python Python if event.data.type == "session.status_idled": session = client.beta.sessions.retrieve(event.data.id) notify_user(session) return "", 204 ``` ```typescript TypeScript if (event.data.type === "session.status_idled") { const session = await client.beta.sessions.retrieve(event.data.id); notifyUser(session); } res.sendStatus(204); ``` ```csharp C# if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled)) { var session = await client.Beta.Sessions.Retrieve(idled.ID); NotifyUser(session); } return Results.StatusCode(204); ``` ```go Go if event.Data.Type == "session.status_idled" { session, err := client.Beta.Sessions.Get(r.Context(), event.Data.ID, anthropic.BetaSessionGetParams{}) if err != nil { panic(err) } notifyUser(session) } w.WriteHeader(http.StatusNoContent) ``` ```java Java event.data().sessionStatusIdled().ifPresent(idled -> { var session = client.beta().sessions().retrieve(idled.id()); notifyUser(session); }); exchange.sendResponseHeaders(204, -1); ``` ```php PHP if ($event->data->type === 'session.status_idled') { $session = $client->beta->sessions->retrieve($event->data->id); notifyUser($session); } http_response_code(204); ``` ```ruby Ruby if event.data.type == :"session.status_idled" session = client.beta.sessions.retrieve(event.data.id) notify_user(session) end status 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` (java, php: `createdAt`; csharp, go: `CreatedAt`)を使用してください。 * **自動無効化：** エンドポイントは、次の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でエンドポイントを再度有効にしてください。エンドポイントが無効化されていた間に発行されたイベントは再送されません。