Webhookをサブスクライブする

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

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



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



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

Claude ConsoleのManage > Webhooksにアクセスしてください。

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となります。トリガーは配信回数ではなく、エンドポイントが中断なく失敗し続けている期間です。単一の2xxでウィンドウがリセットされるため、1つの不安定なイベントでエンドポイントが無効化されることはありません。

  3つすべてが可逆的です。問題を解決した後、Consoleでエンドポイントを再度有効化してください。エンドポイントが無効化されている間に発行されたイベントは再生されません。