조직 웹훅

"Organization webhook"(조직 웹훅) 엔드포인트는 Anthropic이 조직의 사용자 프로필 중 하나를 제한하거나 차단할 때, 그리고 해당 제한 또는 차단이 종료될 때 이벤트를 수신합니다. 조직 웹훅 엔드포인트는 /v1/organizations/webhooks 아래의 Admin API로 관리합니다.

조직의 모든 구성원은 API로 조직 웹훅 엔드포인트를 나열하고 조회할 수 있지만, 엔드포인트를 생성, 변경, 삭제하거나 서명 시크릿을 교체할 수 있는 것은 admin, owner 또는 primary owner 역할을 가진 구성원뿐입니다.

시작하기 전에

다음이 필요합니다:

• 조직 웹훅이 활성화되어 있고 HIPAA 준비가 활성화되어 있지 않은 Claude API 조직. 액세스를 요청하려면 Anthropic 계정 팀에 문의하세요.
• 다음 자격 증명 중 하나:
  • Admin API 키.
  • org:admin 범위를 가진 OAuth bearer 토큰.
  • 워크스페이스로 범위가 지정되지 않은 개인 또는 서비스 계정 키.

이벤트 유형

조직 웹훅 엔드포인트는 두 가지 이벤트 유형을 허용합니다. 두 이벤트 모두 사용자 프로필에 대한 "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는 enac_로 시작하는 조치의 ID입니다:

{
  "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는 프로필이 삭제되었음을 의미합니다.

엔드포인트 필드

조직 웹훅 엔드포인트에는 다음 필드가 있습니다:

{
  "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 사양을 따릅니다. 각 전달에는 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개의 엔드포인트를 반환합니다. 최대 100개를 받으려면 limit을 설정하세요. 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이 엔드포인트 필드의 규칙을 충족하지 않거나, 생성 요청에 이벤트 유형이 나열되지 않은 경우. 오류 메시지에 무엇이 잘못되었는지 표시됩니다.
• 조직에 기본 워크스페이스가 없는 경우.
• 조직의 기본 워크스페이스가 고객 관리형 암호화 키를 사용하기 때문에 조직에서 조직 웹훅을 사용할 수 없는 경우. 오류 메시지에 그렇게 표시됩니다.
• 요청으로 인해 조직의 조직 웹훅 엔드포인트가 32개를 초과하게 되는 경우.
• enabled_events에 이벤트 유형의 두 가지 이외의 이벤트 유형을 넣는 경우. 오류 메시지에 허용되는 유형이 나열됩니다.

계정의 역할에 요청에 필요한 권한이 포함되어 있지 않으면 요청은 403을 반환합니다. 오류에 해당 권한의 이름이 표시됩니다.

다음과 같은 경우 요청은 404를 반환합니다:

• anthropic-beta: webhooks-2026-10-07 헤더를 보내지 않은 경우.
• Anthropic이 귀하의 조직에 조직 웹훅을 활성화하지 않은 경우.
• 조직에 HIPAA 준비가 활성화되어 있는 경우.
• 이러한 요청에서 허용하지 않는 종류의 자격 증명을 사용하는 경우.
• webhook_endpoint_id가 조직의 엔드포인트와 일치하지 않는 경우.

다음과 같은 경우 요청은 409를 반환합니다:

• 요청으로 인해 활성화된 두 조직 웹훅 엔드포인트가 URL을 공유하게 되는 경우.
• 다른 요청이 동시에 조직의 엔드포인트를 변경한 경우. 요청을 재시도하세요.

Compatibility