--- title: 조직 웹훅 url: https://platform.claude.com/docs/ko/manage-claude/organization-webhooks description: 조직의 사용자 프로필에 대한 시행 조치 관련 이벤트를 수신할 웹훅 엔드포인트를 등록합니다. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- "Organization webhook"(조직 웹훅) 엔드포인트는 Anthropic이 조직의 [사용자 프로필](https://platform.claude.com/docs/ko/manage-claude/user-profiles) 중 하나를 제한하거나 차단할 때, 그리고 해당 제한 또는 차단이 종료될 때 이벤트를 수신합니다. 조직 웹훅 엔드포인트는 `/v1/organizations/webhooks` 아래의 Admin API로 관리합니다. 이벤트 전달은 활성화되어 있지 않습니다. Anthropic은 두 이벤트를 전송하지 않으므로 등록한 엔드포인트는 아무것도 수신하지 않습니다. 엔드포인트를 등록하고 이 페이지의 이벤트 형식을 바탕으로 핸들러를 구축할 수는 있습니다. 조직의 모든 구성원은 API로 조직 웹훅 엔드포인트를 나열하고 조회할 수 있지만, 엔드포인트를 생성, 변경, 삭제하거나 서명 시크릿을 교체할 수 있는 것은 admin, owner 또는 primary owner 역할을 가진 구성원뿐입니다. ## 시작하기 전에 다음이 필요합니다: * 조직 웹훅이 활성화되어 있고 [HIPAA 준비](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#hipaa-readiness)가 활성화되어 있지 않은 Claude API 조직. 액세스를 요청하려면 Anthropic 계정 팀에 문의하세요. * 다음 자격 증명 중 하나: * [Admin API 키](https://platform.claude.com/docs/ko/manage-claude/admin-api-keys). * `org:admin` 범위를 가진 [OAuth bearer 토큰](https://platform.claude.com/docs/ko/manage-claude/admin-api#oauth-bearer-token). * 워크스페이스로 범위가 지정되지 않은 [개인 또는 서비스 계정 키](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types). ## 이벤트 유형 조직 웹훅 엔드포인트는 두 가지 이벤트 유형을 허용합니다. 두 이벤트 모두 사용자 프로필에 대한 "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/ko/api/user_profiles/list)하세요. 목록이 끝나기 전에도 응답이 `limit`보다 적은 프로필을 반환하거나 아무것도 반환하지 않을 수 있으므로, `next_page`가 `null`이 될 때까지 계속 페이지를 요청하세요. ### 이벤트에 포함되는 내용 이벤트에는 조치나 프로필 자체가 아니라 ID가 포함됩니다. `data.id`는 프로필의 ID이고, `data.enforcement_action_id`는 `enac_`로 시작하는 조치의 ID입니다: ```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/ko/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`는 프로필이 삭제되었음을 의미합니다. ## 엔드포인트 필드 조직 웹훅 엔드포인트에는 다음 필드가 있습니다: | 필드 | 유형 | 설명 | | ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | `wep_`로 시작하는 엔드포인트의 ID입니다. Anthropic이 설정합니다. | | `url` | string | Anthropic이 이벤트를 전송하는 위치입니다. 포트 443의 HTTPS여야 하며, IP 주소가 아닌 공개 도메인 이름을 사용해야 합니다. 조직 내에서 활성화된 두 조직 웹훅 엔드포인트는 URL을 공유할 수 없습니다. | | `enabled_events` | array of strings | 이 엔드포인트가 수신하는 [이벤트 유형](https://platform.claude.com/docs/ko/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개의 조직 웹훅 엔드포인트를 가질 수 있습니다. 비활성화된 웹훅 엔드포인트도 이 총계에 포함됩니다. ## 전달 전달은 [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/ko/manage-claude/organization-webhooks#before-your-first-event)에서처럼 시행 상태별로 프로필 목록을 조회하세요. * **자동 비활성화:** Anthropic은 다음과 같은 경우 엔드포인트를 비활성화합니다: * 리디렉션(`3xx`)을 반환하는 경우. * URL이 비공개 IP 주소로 확인되는 경우. * 전달이 계속 실패하는 경우. Anthropic은 비활성화된 엔드포인트에 대한 이벤트를 건너뛰며 나중에 전송하지 않습니다. ## 엔드포인트 관리 Admin API로 다음 요청을 할 수 있습니다: | 작업 | 요청 | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 조직의 엔드포인트 나열 | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/ko/api/beta/organization/webhooks/list) | | 엔드포인트 생성 | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/ko/api/beta/organization/webhooks/create) | | 엔드포인트 하나 조회 | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/ko/api/beta/organization/webhooks/retrieve) | | 엔드포인트의 `url`, `name`, `description`, `enabled_events` 또는 `state` 업데이트 | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/ko/api/beta/organization/webhooks/update) | | 엔드포인트 삭제 | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/ko/api/beta/organization/webhooks/delete) | | 서명 시크릿 교체 | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/ko/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개의 엔드포인트를 반환합니다. 최대 100개를 받으려면 `limit`을 설정하세요. `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/ko/manage-claude/organization-webhooks#endpoint-fields)에 표시된 것과 같은 새 엔드포인트와 해당 `signing_secret`입니다. ## 오류 다음과 같은 경우 요청은 `400`을 반환합니다: * `url`이 [엔드포인트 필드](https://platform.claude.com/docs/ko/manage-claude/organization-webhooks#endpoint-fields)의 규칙을 충족하지 않거나, 생성 요청에 이벤트 유형이 나열되지 않은 경우. 오류 메시지에 무엇이 잘못되었는지 표시됩니다. * 조직에 기본 워크스페이스가 없는 경우. * 조직의 기본 워크스페이스가 [고객 관리형 암호화 키](https://platform.claude.com/docs/ko/manage-claude/cmek)를 사용하기 때문에 조직에서 조직 웹훅을 사용할 수 없는 경우. 오류 메시지에 그렇게 표시됩니다. * 요청으로 인해 조직의 조직 웹훅 엔드포인트가 32개를 초과하게 되는 경우. * `enabled_events`에 [이벤트 유형](https://platform.claude.com/docs/ko/manage-claude/organization-webhooks#event-types)의 두 가지 이외의 이벤트 유형을 넣는 경우. 오류 메시지에 허용되는 유형이 나열됩니다. 계정의 역할에 요청에 필요한 권한이 포함되어 있지 않으면 요청은 `403`을 반환합니다. 오류에 해당 권한의 이름이 표시됩니다. 다음과 같은 경우 요청은 `404`를 반환합니다: * `anthropic-beta: webhooks-2026-10-07` 헤더를 보내지 않은 경우. * Anthropic이 귀하의 조직에 조직 웹훅을 활성화하지 않은 경우. * 조직에 HIPAA 준비가 활성화되어 있는 경우. * 이러한 요청에서 허용하지 않는 종류의 자격 증명을 사용하는 경우. * `webhook_endpoint_id`가 조직의 엔드포인트와 일치하지 않는 경우. 다음과 같은 경우 요청은 `409`를 반환합니다: * 요청으로 인해 활성화된 두 조직 웹훅 엔드포인트가 URL을 공유하게 되는 경우. * 다른 요청이 동시에 조직의 엔드포인트를 변경한 경우. 요청을 재시도하세요.