웹훅 구독하기

세션은 장시간 실행되는 상호작용입니다. 대부분의 실시간 상호작용은 SSE 이벤트 스트림을 통해 이루어지지만, 웹훅은 주요 상태 변경을 알려줍니다.

웹훅 이벤트는 전체 객체가 아닌 이벤트 type과 id를 반환합니다. 웹훅 이벤트를 수신하면 GET 호출로 객체를 직접 가져와야 합니다. 이렇게 하면 재시도 시 오래된 데이터가 전달되는 것을 방지하고 모든 전달을 작게 유지할 수 있습니다.



지원되는 이벤트 유형



엔드포인트 등록

Console에서 Manage > Webhooks를 방문하세요.

웹훅 엔드포인트는 다음으로 구성됩니다:

• URL: 공개적으로 확인 가능한 호스트 이름을 가진 443 포트의 HTTPS여야 합니다.
• 이벤트 유형: 이 엔드포인트가 수신하는 data.type 값의 목록입니다. 엔드포인트는 구독한 이벤트만 수신합니다.
• 서명 시크릿: 생성 시 생성되는 whsec_ 접두사가 붙은 32바이트 시크릿입니다. 한 번만 표시되므로 웹훅 전달을 검증할 수 있도록 안전하게 저장하세요.



서명 검증

모든 전달에는 webhook-id, webhook-timestamp, webhook-signature 헤더가 포함됩니다. SDK의 unwrap() 헬퍼를 사용하여 서명을 검증하고 이벤트를 한 번에 파싱하세요. 서명이 유효하지 않거나 페이로드가 5분 이상 지난 경우 예외를 발생시킵니다.

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:
        # 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초 사이의 지터가 적용된 지수 백오프로 최대 3번의 전달 시도를 합니다(이 섹션의 뒷부분에서 설명하는 자동 비활성화를 트리거하는 응답은 절대 재시도되지 않음). 모든 시도는 동일한 event.id를 전달합니다. 마지막 시도가 실패하면 이벤트는 폐기됩니다. 나중에 전달하기 위해 대기열에 추가되지 않으며 손실되었다는 신호도 없습니다. 웹훅은 내구성 있는 로그가 아니므로 모든 전환을 관찰해야 하는 경우 API를 통해 리소스를 나열하거나 가져와서 조정하세요.

• 타임스탬프: webhook-timestamp 헤더는 전달 시도가 서명될 때 기록되며 재시도할 때마다 다시 생성되므로, 재시도가 SDK의 최신성 검사에 의해 거부되지 않습니다. 이는 이벤트가 아닌 전달 시도의 시계입니다. 이벤트가 발생한 시점은 이벤트 페이로드의 created_at을 사용하세요.

• 자동 비활성화: 다음 세 가지 경우에 엔드포인트는 기계가 읽을 수 있는 disabled_reason과 함께 자동으로 disabled로 설정됩니다:

  • 엔드포인트가 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에서 엔드포인트를 다시 활성화하세요. 엔드포인트가 비활성화된 동안 발생한 이벤트는 재전송되지 않습니다.