Claude Code HTTP Hook 기능 추가: 자동화 워크플로우 확장 방법 정리

최근 **Claude Code**에 새로운 HTTP Hook 기능이 추가되었습니다. 이 기능은 Claude Code의 실행 과정에서 발생하는 다양한 이벤트를 외부 시스템과 연동하여 자동화할 수 있도록 지원합니다. 기존의 Command Hook 방식보다 설정과 확장이 쉬워졌으며, 웹 서버나 API 기반 서비스와 연결해 보다 체계적인 개발 환경을 구축할 수 있습니다.

HTTP Hook을 활용하면 Claude Code의 상태를 모니터링하거나 권한 정책을 관리하고, 코드 변경이나 작업 이벤트에 맞춰 자동으로 배포 또는 데이터 기록을 수행하는 시스템을 만들 수 있습니다. 이 글

반응형

에서는 Claude Code Hooks의 개념과 구조, HTTP Hook의 동작 방식, 설정 방법, 그리고 활용 사례까지 정리해보겠습니다.

 

---

Claude Code Hooks 개념

Claude Code Hooks는 Claude Code가 동작하는 과정에서 특정 이벤트가 발생할 때 자동으로 실행되는 사용자 정의 작업입니다. 이 기능을 통해 개발자는 Claude Code의 실행 흐름을 제어하거나 외부 시스템과 연동할 수 있습니다.

Hook은 다음과 같은 과정으로 동작합니다.

1. Claude Code 실행 과정에서 특정 이벤트 발생
2. 이벤트에 설정된 Matcher 조건 확인
3. 조건이 일치하면 Hook 실행
4. Hook 실행 결과를 기반으로 Claude Code가 다음 동작을 결정

이를 활용하면 개발 환경에서 다양한 자동화 작업을 구현할 수 있습니다.

예를 들어 다음과 같은 작업이 가능합니다.

• 위험한 명령어 실행 차단
• 코드 수정 이후 자동 검사 수행
• 작업 로그 기록
• 외부 정책 서버와 권한 검증
• 배포 자동화 트리거

---

Claude Code Hook 이벤트 구조

Claude Code는 다양한 실행 단계에서 Hook 이벤트를 발생시킵니다. 주요 이벤트는 다음과 같습니다.

이벤트	설명
SessionStart	세션이 시작되거나 재개될 때
UserPromptSubmit	사용자가 프롬프트를 제출할 때
PreToolUse	Tool 실행 전에 발생
PostToolUse	Tool 실행 이후 발생
PostToolUseFailure	Tool 실행 실패 시 발생
PermissionRequest	권한 요청 발생 시
SubagentStart	서브 에이전트 시작 시
SubagentStop	서브 에이전트 종료 시
Stop	Claude 응답 완료 시
SessionEnd	세션 종료 시

이벤트를 기반으로 Hook을 설정하면 Claude Code의 특정 동작을 세밀하게 제어할 수 있습니다. 예를 들어 PreToolUse 이벤트를 사용하면 특정 명령 실행 전에 검증 로직을 실행하거나 실행 자체를 차단할 수 있습니다.

---

HTTP Hook 기능과 기존 Command Hook의 차이

기존 Hook 방식은 주로 로컬 스크립트를 실행하는 Command Hook이었습니다. 하지만 HTTP Hook이 추가되면서 외부 서버와의 연동이 훨씬 간편해졌습니다.

Command Hook의 특징은 다음과 같습니다.

• 로컬 쉘 스크립트 실행
• JSON 데이터를 stdin으로 전달
• 결과를 stdout으로 반환

반면 HTTP Hook은 다음과 같은 방식으로 동작합니다.

• 이벤트 데이터를 HTTP POST 요청으로 전송
• 외부 서버에서 데이터를 분석 및 처리
• JSON 응답을 통해 실행 허용 여부 결정

이 방식은 특히 다음과 같은 상황에서 유용합니다.

• 조직 단위 정책 관리
• 중앙화된 권한 검증 시스템 구축
• 개발 작업 로그 저장
• CI/CD 파이프라인 연동
• 자동 배포 트리거

---

HTTP Hook 동작 방식

HTTP Hook은 다음 단계로 동작합니다.

1. Claude Code에서 이벤트 발생
2. 이벤트 정보를 JSON 형태로 생성
3. 지정된 URL로 HTTP POST 요청 전송
4. 서버에서 이벤트 데이터를 분석
5. JSON 응답 반환
6. Claude Code가 응답 결과에 따라 동작 수행

예를 들어 Bash 명령 실행 전에 Hook이 호출될 경우 다음과 같은 요청이 전송됩니다.

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build"
  }
}

서버는 이 요청을 분석하여 실행 여부를 판단하고 결과를 반환합니다.

예시 응답

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked"
  }
}

이 응답이 반환되면 Claude Code는 해당 명령 실행을 차단합니다.

---

HTTP Hook 설정 예제

다음은 Bash Tool 실행 전에 HTTP Hook을 호출하는 기본 설정 예시입니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

설정 항목 설명

• type: Hook 실행 방식 지정 (HTTP 사용)
• url: 이벤트 데이터를 전달할 서버 주소
• matcher: 특정 Tool에서만 Hook 실행
• timeout: 서버 응답 대기 시간
• headers: 인증 정보 전달
• allowedEnvVars: 환경 변수 사용 허용 목록

이 설정을 적용하면 Bash 명령 실행 전에 항상 지정된 서버로 검증 요청이 전달됩니다.

---

Matcher 패턴을 통한 실행 조건 제어

Hook은 Matcher를 사용하여 실행 조건을 제어할 수 있습니다. Matcher는 정규식을 기반으로 특정 이벤트만 필터링합니다.

예시 Matcher 패턴

Matcher	의미
Bash	Bash tool 실행 시
Edit|Write	파일 수정 또는 생성 시
mcp__memory__.*	Memory MCP 서버 관련 tool
mcp__.__write.	모든 MCP write 작업

예를 들어 파일 수정 이후 자동으로 lint 검사 스크립트를 실행하려면 다음과 같이 설정할 수 있습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

---

Hook 설정 위치

Hook 설정은 여러 위치에서 관리할 수 있으며 위치에 따라 적용 범위가 달라집니다.

위치	적용 범위
~/.claude/settings.json	개인 환경 전체
.claude/settings.json	특정 프로젝트
.claude/settings.local.json	로컬 전용 설정
조직 정책 설정	조직 전체 정책
플러그인 hooks	플러그인 활성 시 적용

일반적으로 프로젝트 단위 자동화를 위해 .claude/settings.json 파일에 설정을 추가하는 방식이 많이 사용됩니다.

---

HTTP Hook 활용 사례

HTTP Hook을 활용하면 다양한 자동화 시스템을 구축할 수 있습니다.

첫 번째는 위험 명령어 차단 시스템입니다. rm -rf, sudo와 같은 위험한 명령을 서버에서 검사하여 실행을 제한할 수 있습니다.

두 번째는 코드 정책 검증입니다. 코드 스타일 검사, 보안 규칙 검사, 조직 내부 규정 검증 등을 자동으로 수행할 수 있습니다.

세 번째는 개발 활동 모니터링입니다. Hook 이벤트를 데이터베이스에 기록하면 개발 활동 로그나 Tool 사용 기록을 분석할 수 있습니다.

네 번째는 자동 배포 시스템입니다. 코드 수정이나 특정 작업 완료 시 Hook을 통해 CI/CD 파이프라인을 실행할 수 있습니다.

---

728x90

Claude Code의 HTTP Hook 기능은 개발 자동화와 정책 관리 측면에서 매우 중요한 확장 기능입니다. 기존의 로컬 스크립트 기반 자동화에서 벗어나 외부 서버와 연동하는 구조를 통해 훨씬 확장성이 높은 시스템을 구축할 수 있습니다.

핵심 내용을 정리하면 다음과 같습니다.

• Claude Code 이벤트를 HTTP API로 전달 가능
• 외부 서버에서 정책 검증 및 자동화 로직 처리
• 개발 작업 로그 및 상태 관리 시스템 구축 가능
• CI/CD, 보안 정책, 모니터링 시스템과 쉽게 연동 가능

HTTP Hook 기능을 활용하면 Claude Code를 단순한 코드 생성 도구가 아니라 자동화된 개발 플랫폼으로 확장할 수 있습니다. 앞으로 AI 기반 개발 환경에서 이러한 Hook 기반 자동화 구조는 개발 생산성과 협업 효율을 크게 높이는 핵심 기술로 활용될 것으로 기대됩니다.

300x250

https://code.claude.com/docs/en/hooks

Hooks reference - Claude Code Docs