訂閱 webhooks

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

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



支援的事件類型



註冊端點

前往 Console 中的 Manage > Webhooks。

Webhook 端點包含：

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



驗證簽章

每次傳遞都帶有 webhook-id、webhook-timestamp 和 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:
        # 若簽章無效或 payload 過期，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 兩次，那是重試，您可以捨棄它。



傳遞行為

• 重複： 端點可能會多次收到相同的事件，且每次嘗試都會傳遞相同的最上層 event.id（與 webhook-id 標頭的值相同）。請依此進行去重。

• 訂閱範圍： 事件只會傳遞給在其發出當下已訂閱該類型的端點。在沒有任何端點訂閱其類型時發出的事件永遠不會被傳遞，之後訂閱也不會回補，因此請在需要之前先訂閱事件類型。

• 不保證順序。 事件不會依發生順序傳遞：即使成果先產生，session.status_idled 也可能在 session.outcome_evaluation_ended 之前到達，而同一資源的 .deleted 事件可能在 .archived 事件之前到達。請根據您取得的資源來驅動您的狀態，而非根據事件到達的順序。

• 重試： 對於每個端點和事件，Anthropic 最多進行三次傳遞嘗試（觸發自動停用的回應（本節稍後說明）永遠不會重試），並在 5 到 120 秒之間使用帶有抖動的指數退避。每次嘗試都會傳遞相同的 event.id。最後一次嘗試失敗後，該事件會被丟棄：它不會排入佇列以供稍後傳遞，也不會有任何訊號表示它已遺失。Webhooks 不是持久性日誌，因此如果您需要觀察每次轉換，請透過 API 列出或取得資源來進行對帳。

• 時間戳記： webhook-timestamp 標頭是在傳遞嘗試被簽署時蓋上的，並且在每次重試時重新產生，因此重試不會被 SDK 的新鮮度檢查拒絕。它是傳遞嘗試的時鐘，而非事件的時鐘：請使用事件酬載的 created_at 來判斷事件發生的時間。

• 自動停用： 在三種情況下，端點會自動設定為 disabled，並附帶機器可讀的 disabled_reason：

  • 端點回傳 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 會重設該時間窗，因此單一不穩定的事件不會停用端點。

  這三種情況都是可逆的：在您解決問題後，於 Console 中重新啟用端點。端點停用期間發出的事件不會重播。