組織 webhook

當 Anthropic 限制或封鎖您組織的某個使用者設定檔，以及該限制或封鎖結束時，組織 webhook 端點會收到一個事件。您可以透過 Admin API 在 /v1/organizations/webhooks 下管理它。

您組織的任何成員都可以透過 API 列出和檢視組織 webhook 端點，但只有具備管理員（admin）、擁有者（owner）或主要擁有者（primary owner）角色的成員，才能建立、變更或刪除端點，或更換其簽署密鑰。

開始之前

您需要以下項目：

• 一個位於 Claude API 上、已開啟組織 webhook 且未啟用 HIPAA 就緒的組織。如需申請存取權限，請聯繫您的 Anthropic 客戶團隊。
• 下列其中一種憑證：
  • Admin API 金鑰。
  • 具有 org:admin 範圍的 OAuth bearer 權杖。
  • 未限定於某個工作區的個人或服務帳戶金鑰。

事件類型

組織 webhook 端點接受兩種事件類型。兩者都與使用者設定檔上的「enforcement action」（強制措施）有關。強制措施是 Anthropic 對設定檔所代表之終端客戶施加的限制或封鎖。

刪除設定檔會結束其所有開啟中的措施，但不會產生 user_profile.enforcement_action_resolved 事件。

在您收到第一個事件之前

在您的組織開啟強制措施功能之前，您的設定檔不會有 enforcement_status 和 enforcement_actions 欄位。在此之前，以及在任何 anthropic-beta 標頭含有 user-profiles-2026-09-04 或更早值的請求中，回應都會省略這些欄位，且 enforcement_status[] 清單篩選器會傳回 400。若要取得這些欄位，請從您的請求中移除該值。

如果某項強制措施是在 Anthropic 為您的組織開啟強制措施和事件傳遞功能之前，或在您註冊端點之前開啟的，您不會收到該措施的 user_profile.enforcement_action_opened 事件。該措施仍會顯示在設定檔上。若要找出這些措施，請使用 enforcement_status[]=restricted 和 enforcement_status[]=banned 列出您的設定檔。在清單結束之前，回應傳回的設定檔數量可能少於 limit，甚至沒有任何設定檔，因此請持續請求分頁，直到 next_page 為 null。

事件包含的內容

事件攜帶的是 ID，而不是措施或設定檔本身。data.id 是設定檔的 ID，data.enforcement_action_id 是措施的 ID，以 enac_ 開頭：

{
  "type": "event",
  "id": "whe_4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c",
  "created_at": "2026-10-15T17:02:41Z",
  "data": {
    "type": "user_profile.enforcement_action_opened",
    "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    "enforcement_action_id": "enac_011CZkZEq4TnWb7xLfRgPm2v",
    "organization_id": "org_011CZkZBj9RsYd3wNcHvKq6t"
  }
}

若要查看變更內容，請使用 data.id，透過 client.user_profiles.retrieve() 擷取設定檔。其 enforcement_actions 清單會顯示其開啟中的措施。每項措施都有一個 type（restriction 或 ban）、一個 id、一個 reason、一個 opened_at 時間，以及一個 expires_at 時間或 null。enforcement_status 會彙總這些措施：有封鎖開啟時為 banned，有任何其他措施開啟時為 restricted，沒有任何措施開啟時為 unrestricted。請將任何其他值視為 restricted。

Anthropic 只會在設定檔顯示變更之後才傳送事件，因此您擷取的設定檔會顯示該變更或之後的變更。事件可能會延遲送達或不按順序送達，因此請以設定檔的目前狀態為準，而不是事件送達的順序。在 user_profile.enforcement_action_resolved 之後，已解除的措施將不再出現在清單中。404 表示該設定檔已被刪除。

端點欄位

組織 webhook 端點具有以下欄位：

{
  "id": "wep_011CZkZDf8HnUq2mTxRbVn4s",
  "url": "https://example.com/anthropic-webhooks",
  "name": "Enforcement actions",
  "description": "",
  "enabled_events": [
    "user_profile.enforcement_action_opened",
    "user_profile.enforcement_action_resolved"
  ],
  "state": "enabled",
  "disabled_reason": "",
  "created_at": "2026-10-20T19:00:00Z",
  "updated_at": "2026-10-20T19:00:00Z"
}

一個組織最多可以有 32 個組織 webhook 端點。已停用的 webhook 端點仍會計入此總數。

傳遞

傳遞遵循 Standard Webhooks 規範。每次傳遞都帶有 webhook-id、webhook-timestamp 和 webhook-signature 標頭。在信任某個事件之前，請使用任何 Standard Webhooks 函式庫，以端點的簽署密鑰驗證其簽章。

請在 5 秒內傳回任何 2xx 狀態，並在之後再進行耗時的工作。任何其他回應或沒有回應，都會被視為一次失敗的嘗試。

• 重複： 端點可能會多次收到同一個事件，且事件 id 相同（與 webhook-id 標頭的值相同）。請依此進行去重複處理。

• 重試： 如果傳遞失敗，Anthropic 會在接下來的幾分鐘內重試數次。如果每次嘗試都失敗，Anthropic 會捨棄該事件。若要補上遺漏的事件，請依強制措施狀態列出您的設定檔，如在您收到第一個事件之前所述。

• 自動停用： 在以下情況下，Anthropic 會停用端點：

  • 它傳回重新導向（3xx）。
  • 其 URL 解析為非公開的 IP 位址。
  • 其傳遞持續失敗。

  Anthropic 會略過已停用端點的事件，且之後不會再傳送。

管理端點

透過 Admin API，您可以發出以下請求：

在更新中，enabled_events 會取代端點的整個事件類型清單。空清單不會清除該清單：端點會保留原有的事件類型。若要停止傳遞，請傳送 "state": "disabled" 或刪除該端點。

若要重新開啟端點（包括在 Anthropic 停用它之後），請在更新請求中傳送 "state": "enabled"。

當您更換簽署密鑰時，舊密鑰會立即失效。從那時起的傳遞（包括先前事件的重試）都會以新密鑰簽署，因此請立即更新您的接收端。

請在每個請求中傳送 anthropic-beta: webhooks-2026-10-07 標頭。SDK 和 CLI 會為您傳送它。此範例使用來自 ANTHROPIC_API_KEY 的 Admin API 金鑰，列出您組織的端點。

client = anthropic.Anthropic()

endpoints = client.beta.organization.webhooks.list()

for endpoint in endpoints:
    print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})")

沒有任何端點時，API 會傳回空清單：

{
  "data": [],
  "has_more": false
}

清單預設最多傳回 20 個端點。設定 limit 最多可取得 100 個。如果 has_more 為 true，請將回應的 last_id 作為 after_id 傳入，以取得下一頁。

此範例建立一個接收兩種事件類型的端點：

client = anthropic.Anthropic()

endpoint = client.beta.organization.webhooks.create(
    url="https://example.com/anthropic-webhooks",
    name="Enforcement actions",
    enabled_events=[
        "user_profile.enforcement_action_opened",
        "user_profile.enforcement_action_resolved",
    ],
)

print(endpoint.id)

回應是新的端點（如端點欄位所示），外加其 signing_secret。

錯誤

在以下情況下，請求會傳回 400：

• 其 url 不符合端點欄位中的規則，或建立請求未列出任何事件類型。錯誤訊息會說明問題所在。
• 您的組織沒有預設工作區。
• 由於您組織的預設工作區使用客戶管理的加密金鑰，因此您的組織無法使用組織 webhook。錯誤訊息會說明這一點。
• 它會使您的組織擁有超過 32 個組織 webhook 端點。
• 它在 enabled_events 中放入了事件類型中兩種類型以外的事件類型。錯誤訊息會列出可接受的類型。

如果您帳戶的角色不包含請求所需的權限，請求會傳回 403。錯誤會指出該權限的名稱。

在以下情況下，請求會傳回 404：

• 它未傳送 anthropic-beta: webhooks-2026-10-07 標頭。
• Anthropic 尚未為您的組織開啟組織 webhook。
• 您的組織已啟用 HIPAA 就緒。
• 它使用了這些請求不接受的憑證類型。
• 其 webhook_endpoint_id 與您組織中的任何端點都不相符。

在以下情況下，請求會傳回 409：

• 它會使兩個已啟用的組織 webhook 端點共用同一個 URL。
• 另一個請求同時變更了您組織的端點。請重試該請求。

Compatibility