Webhookをサブスクライブする

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

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

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

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

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

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

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

署名を検証する

すべての配信にはX-Webhook-Signatureヘッダーが含まれています。SDKのunwrap()ヘルパーを使用して、署名の検証とイベントの解析を一度に行います。署名が無効な場合、またはペイロードが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": "event_01ABC...",
  "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回受信した場合、それは再試行であり、破棄できます。

配信動作

• 順序は保証されません。 アウトカムが先に生成された場合でも、session.status_idledがsession.outcome_evaluation_endedより先に到着する可能性があります。順序が重要な場合は、created_atタイムスタンプを使用してソートしてください。
• 再試行: Anthropicは少なくとも1回再試行します。再試行では同じevent.idが配信されます。
• リダイレクトは追跡されません。 3xxは失敗として扱われます。エンドポイントが移動した場合は、ConsoleでURLを更新してください。
• 自動無効化: 約20回連続で配信に失敗した後、またはホスト名がプライベートIPに解決される場合やエンドポイントがリダイレクトを返す場合は即座に、エンドポイントは機械可読なdisabled_reasonとともに自動的にdisabledに設定されます。問題を解決した後、Consoleで手動で再度有効化してください。