訂閱 webhook

「Session」（工作階段）是長時間執行的互動。雖然大多數即時互動是透過 SSE 事件串流進行，但 webhook 會在主要狀態變更時通知您。

Webhook 事件會回傳事件的 type 和 id，而非完整物件。當您收到 webhook 事件時，需要透過 GET 呼叫直接擷取該物件。這可避免在重試時傳遞過時的資料，並使每次傳遞保持精簡。



支援的事件類型



註冊端點

請前往 Console 中的 Manage > Webhooks。

Webhook 端點包含以下項目：

• URL： 必須是使用連接埠 443 的 HTTPS，且主機名稱可公開解析。
• 事件類型： 此端點接收的 data.type 值清單。端點只會接收其訂閱的事件，以及測試事件（請參閱傳遞行為）。
• 簽署密鑰： 建立時產生的 32 位元組、以 whsec_ 為前綴的密鑰。它只會顯示一次，因此請安全地儲存以驗證 webhook 傳遞。



驗證簽章

每次傳遞都帶有 X-Webhook-Signature 標頭。使用 SDK 的 unwrap() 輔助函式可一步完成簽章驗證和事件解析。如果簽章無效或酬載已超過五分鐘，它會擲回例外。

將 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 兩次，表示這是重試，您可以將其捨棄。



傳遞行為

• 不保證順序。 session.status_idled 可能在 session.outcome_evaluation_ended 之前到達，即使結果是先產生的。如果順序很重要，請使用 created_at 時間戳記進行排序。
• 重試： Anthropic 至少會重試一次。重試會傳遞相同的 event.id。
• 不會跟隨重新導向。 3xx 會被視為失敗。如果您的端點移動了，請在 Console 中更新 URL。
• 自動停用： 在大約連續 20 次傳遞失敗後，端點會自動設定為 disabled 並附帶機器可讀的 disabled_reason；如果主機名稱解析為私有 IP 或端點回傳重新導向，則會立即停用。解決問題後，請在 Console 中手動重新啟用。