웹훅 구독하기

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

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

지원되는 이벤트 유형

엔드포인트 등록하기

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

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

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

서명 확인하기

모든 전달에는 X-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": "event_01ABC...",
  "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를 두 번 받으면 재시도이므로 폐기할 수 있습니다.

전달 동작

• 순서는 보장되지 않습니다. 결과가 먼저 생성되었더라도 session.status_idled가 session.outcome_evaluation_ended보다 먼저 도착할 수 있습니다. 순서가 중요한 경우 created_at 타임스탬프를 사용하여 정렬하세요.
• 재시도: Anthropic은 최소 한 번 재시도합니다. 재시도는 동일한 event.id를 전달합니다.
• 리디렉션은 따르지 않습니다. 3xx는 실패로 처리됩니다. 엔드포인트가 이동한 경우 Console에서 URL을 업데이트하세요.
• 자동 비활성화: 약 20회 연속 전달 실패 후, 또는 호스트 이름이 사설 IP로 확인되거나 엔드포인트가 리디렉션을 반환하는 경우 즉시, 엔드포인트가 기계 판독 가능한 disabled_reason과 함께 자동으로 disabled로 설정됩니다. 문제를 해결한 후 Console에서 수동으로 다시 활성화하세요.