--- title: 組織 webhook url: https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks description: 註冊 webhook 端點，以接收與您組織的使用者設定檔相關之強制措施事件。 featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- 當 Anthropic 限制或封鎖您組織的某個[使用者設定檔](https://platform.claude.com/docs/zh-TW/manage-claude/user-profiles)，以及該限制或封鎖結束時，組織 webhook 端點會收到一個事件。您可以透過 Admin API 在 `/v1/organizations/webhooks` 下管理它。 事件傳遞尚未上線：Anthropic 不會傳送這兩種事件，因此您註冊的端點不會收到任何內容。您可以註冊端點，並依照本頁的事件格式建置您的處理程式。 您組織的任何成員都可以透過 API 列出和檢視組織 webhook 端點，但只有具備管理員（admin）、擁有者（owner）或主要擁有者（primary owner）角色的成員，才能建立、變更或刪除端點，或更換其簽署密鑰。 ## 開始之前 您需要以下項目： * 一個位於 Claude API 上、已開啟組織 webhook 且未啟用 [HIPAA 就緒](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#hipaa-readiness)的組織。如需申請存取權限，請聯繫您的 Anthropic 客戶團隊。 * 下列其中一種憑證： * [Admin API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api-keys)。 * 具有 `org:admin` 範圍的 [OAuth bearer 權杖](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api#oauth-bearer-token)。 * 未限定於某個工作區的[個人或服務帳戶金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-types)。 ## 事件類型 組織 webhook 端點接受兩種事件類型。兩者都與使用者設定檔上的「enforcement action」（強制措施）有關。強制措施是 Anthropic 對設定檔所代表之終端客戶施加的限制或封鎖。 | 事件 | 觸發條件 | | ------------------------------------------ | --------------------------------------------- | | `user_profile.enforcement_action_opened` | Anthropic 對某個使用者設定檔開啟一項強制措施。 | | `user_profile.enforcement_action_resolved` | 一項強制措施結束。Anthropic 解除了它，或其 `expires_at` 時間已過。 | 刪除設定檔會結束其所有開啟中的措施，但不會產生 `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` [列出您的設定檔](https://platform.claude.com/docs/zh-TW/api/user_profiles/list)。在清單結束之前，回應傳回的設定檔數量可能少於 `limit`，甚至沒有任何設定檔，因此請持續請求分頁，直到 `next_page` 為 `null`。 ### 事件包含的內容 事件攜帶的是 ID，而不是措施或設定檔本身。`data.id` 是設定檔的 ID，`data.enforcement_action_id` 是措施的 ID，以 `enac_` 開頭： ```json { "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`，透過 `GET /v1/user_profiles/{id}` (python, ruby: `client.user_profiles.retrieve()`; typescript: `client.userProfiles.retrieve()`; go: `client.UserProfiles.Get()`; java: `client.userProfiles().retrieve()`; csharp: `client.UserProfiles.Retrieve()`; php: `$client->userProfiles->retrieve()`; cli: `ant user-profiles retrieve`) [擷取設定檔](https://platform.claude.com/docs/zh-TW/api/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` | string | 端點的 ID，以 `wep_` 開頭。由 Anthropic 設定。 | | `url` | string | Anthropic 傳送事件的目的地。必須是連接埠 443 上的 HTTPS，並使用公開網域名稱，而非 IP 位址。您組織中的兩個已啟用的組織 webhook 端點不能共用同一個 URL。 | | `enabled_events` | array of strings | 此端點接收的[事件類型](https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks#event-types)。建立請求必須至少列出一種。 | | `name` | string | 供您自行使用的選用標籤。 | | `description` | string | 供您自行使用的選用說明。 | | `state` | string | `enabled` 或 `disabled`。 | | `disabled_reason` | string | Anthropic 停用該端點的原因。否則為空。 | | `created_at` | string | 端點的建立時間。由 Anthropic 設定。 | | `updated_at` | string | 端點的最後變更時間。由 Anthropic 設定。 | | `signing_secret` | string | 以 `whsec_` 為前綴的密鑰，隨端點一起建立。只有建立端點或更換密鑰的回應會包含它，因此請妥善保存。 | ```json { "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](https://www.standardwebhooks.com/) 規範。每次傳遞都帶有 `webhook-id`、`webhook-timestamp` 和 `webhook-signature` 標頭。在信任某個事件之前，請使用任何 Standard Webhooks 函式庫，以端點的簽署密鑰驗證其簽章。 請在 5 秒內傳回任何 `2xx` 狀態，並在之後再進行耗時的工作。任何其他回應或沒有回應，都會被視為一次失敗的嘗試。 * **重複：** 端點可能會多次收到同一個事件，且事件 `id` 相同（與 `webhook-id` 標頭的值相同）。請依此進行去重複處理。 * **重試：** 如果傳遞失敗，Anthropic 會在接下來的幾分鐘內重試數次。如果每次嘗試都失敗，Anthropic 會捨棄該事件。若要補上遺漏的事件，請依強制措施狀態列出您的設定檔，如[在您收到第一個事件之前](https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks#before-your-first-event)所述。 * **自動停用：** 在以下情況下，Anthropic 會停用端點： * 它傳回重新導向（`3xx`）。 * 其 URL 解析為非公開的 IP 位址。 * 其傳遞持續失敗。 Anthropic 會略過已停用端點的事件，且之後不會再傳送。 ## 管理端點 透過 Admin API，您可以發出以下請求： | 工作 | 請求 | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 列出您組織的端點 | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/list) | | 建立端點 | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/create) | | 取得單一端點 | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/retrieve) | | 更新端點的 `url`、`name`、`description`、`enabled_events` 或 `state` | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/update) | | 刪除端點 | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/delete) | | 更換簽署密鑰 | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/zh-TW/api/beta/organization/webhooks/regenerate_signing_secret) | 在更新中，`enabled_events` 會取代端點的整個事件類型清單。空清單不會清除該清單：端點會保留原有的事件類型。若要停止傳遞，請傳送 `"state": "disabled"` 或刪除該端點。 若要重新開啟端點（包括在 Anthropic 停用它之後），請在更新請求中傳送 `"state": "enabled"`。 當您更換簽署密鑰時，舊密鑰會立即失效。從那時起的傳遞（包括先前事件的重試）都會以新密鑰簽署，因此請立即更新您的接收端。 請在每個請求中傳送 `anthropic-beta: webhooks-2026-10-07` 標頭。SDK 和 CLI 會為您傳送它。此範例使用來自 `ANTHROPIC_API_KEY` 的 Admin API 金鑰，列出您組織的端點。 ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" ``` ```bash CLI ant beta:organization:webhooks list ``` ```python Python client = anthropic.Anthropic() endpoints = client.beta.organization.webhooks.list() for endpoint in endpoints: print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})") ``` ```typescript TypeScript const client = new Anthropic(); const endpoints = await client.beta.organization.webhooks.list(); for await (const endpoint of endpoints) { console.log(`${endpoint.id}: ${endpoint.url} (${endpoint.state})`); } ``` ```csharp C# AnthropicClient client = new(); var page = await client.Beta.Organization.Webhooks.List(); await foreach (var endpoint in page.Paginate()) { Console.WriteLine($"{endpoint.ID}: {endpoint.Url} ({endpoint.State.Raw()})"); } ``` ```go Go client := anthropic.NewClient() endpoints := client.Beta.Organization.Webhooks.ListAutoPaging(context.Background(), anthropic.BetaOrganizationWebhookListParams{}) for endpoints.Next() { endpoint := endpoints.Current() fmt.Printf("%s: %s (%s)\n", endpoint.ID, endpoint.URL, endpoint.State) } if err := endpoints.Err(); err != nil { log.Fatal(err) } ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var endpoints = client.beta().organization().webhooks().list(); for (var endpoint : endpoints.autoPager()) { IO.println(endpoint.id() + ": " + endpoint.url() + " (" + endpoint.state().asString() + ")"); } ``` ```php PHP $client = new Client(); $endpoints = $client->beta->organization->webhooks->list(); foreach ($endpoints->pagingEachItem() as $endpoint) { echo "{$endpoint->id}: {$endpoint->url} ({$endpoint->state})\n"; } ``` ```ruby Ruby client = Anthropic::Client.new endpoints = client.beta.organization.webhooks.list endpoints.auto_paging_each do |endpoint| puts "#{endpoint.id}: #{endpoint.url} (#{endpoint.state})" end ``` 沒有任何端點時，API 會傳回空清單： ```json { "data": [], "has_more": false } ``` 清單預設最多傳回 20 個端點。設定 `limit` 最多可取得 100 個。如果 `has_more` 為 `true`，請將回應的 `last_id` 作為 `after_id` 傳入，以取得下一頁。 此範例建立一個接收兩種事件類型的端點： ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" \ -H "content-type: application/json" \ -d '{ "url": "https://example.com/anthropic-webhooks", "name": "Enforcement actions", "enabled_events": [ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved" ] }' ``` ```bash CLI ant beta:organization:webhooks create \ --url https://example.com/anthropic-webhooks \ --name "Enforcement actions" \ --enabled-event user_profile.enforcement_action_opened \ --enabled-event user_profile.enforcement_action_resolved ``` ```python Python 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) ``` ```typescript TypeScript const client = new Anthropic(); const endpoint = await 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" ] }); console.log(endpoint.id); ``` ```csharp C# using Anthropic.Models.Beta.Organization.Webhooks; AnthropicClient client = new(); var endpoint = await client.Beta.Organization.Webhooks.Create(new WebhookCreateParams { UrlValue = "https://example.com/anthropic-webhooks", Name = "Enforcement actions", EnabledEvents = [ EnabledEvent.UserProfileEnforcementActionOpened, EnabledEvent.UserProfileEnforcementActionResolved, ], }); Console.WriteLine(endpoint.ID); ``` ```go Go client := anthropic.NewClient() endpoint, err := client.Beta.Organization.Webhooks.New(context.Background(), anthropic.BetaOrganizationWebhookNewParams{ URL: "https://example.com/anthropic-webhooks", Name: anthropic.String("Enforcement actions"), EnabledEvents: []string{ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved", }, }) if err != nil { log.Fatal(err) } fmt.Println(endpoint.ID) ``` ```java Java import com.anthropic.models.beta.organization.webhooks.WebhookCreateParams; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = WebhookCreateParams.builder() .url("https://example.com/anthropic-webhooks") .name("Enforcement actions") .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_OPENED) .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_RESOLVED) .build(); var endpoint = client.beta().organization().webhooks().create(params); IO.println(endpoint.id()); } ``` ```php PHP $client = new Client(); $endpoint = $client->beta->organization->webhooks->create( url: 'https://example.com/anthropic-webhooks', name: 'Enforcement actions', enabledEvents: [ 'user_profile.enforcement_action_opened', 'user_profile.enforcement_action_resolved', ], ); echo $endpoint->id, "\n"; ``` ```ruby Ruby client = Anthropic::Client.new 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" ] ) puts endpoint.id ``` 回應是新的端點（如[端點欄位](https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks#endpoint-fields)所示），外加其 `signing_secret`。 ## 錯誤 在以下情況下，請求會傳回 `400`： * 其 `url` 不符合[端點欄位](https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks#endpoint-fields)中的規則，或建立請求未列出任何事件類型。錯誤訊息會說明問題所在。 * 您的組織沒有預設工作區。 * 由於您組織的預設工作區使用[客戶管理的加密金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)，因此您的組織無法使用組織 webhook。錯誤訊息會說明這一點。 * 它會使您的組織擁有超過 32 個組織 webhook 端點。 * 它在 `enabled_events` 中放入了[事件類型](https://platform.claude.com/docs/zh-TW/manage-claude/organization-webhooks#event-types)中兩種類型以外的事件類型。錯誤訊息會列出可接受的類型。 如果您帳戶的角色不包含請求所需的權限，請求會傳回 `403`。錯誤會指出該權限的名稱。 在以下情況下，請求會傳回 `404`： * 它未傳送 `anthropic-beta: webhooks-2026-10-07` 標頭。 * Anthropic 尚未為您的組織開啟組織 webhook。 * 您的組織已啟用 HIPAA 就緒。 * 它使用了這些請求不接受的憑證類型。 * 其 `webhook_endpoint_id` 與您組織中的任何端點都不相符。 在以下情況下，請求會傳回 `409`： * 它會使兩個已啟用的組織 webhook 端點共用同一個 URL。 * 另一個請求同時變更了您組織的端點。請重試該請求。