🐙

GitHub Webhook은 어떻게 동작하나?

git push → HTTP POST → CI/CD 트리거

GitHub Webhook은 Repository Settings > Webhooks에서 URL을 등록하면 동작합니다. 이벤트 발생 시 GitHub가 해당 URL로 JSON payload와 함께 HTTP POST를 보냅니다. X-Hub-Signature-256 헤더로 HMAC 서명을 포함하여 요청의 진위를 검증할 수 있습니다. 수신 서버는 200 OK를 10초 내에 반환해야 하며, 실패 시 GitHub가 자동으로 재시도합니다.

구조 다이어그램

사전 설정

👤

Repository Owner

Settings → Webhooks → Add →

🐙

GitHub

URL + Secret 저장

이벤트 발생 시

👨‍💻

개발자

git push

→

🐙

GitHub

push event 감지

HTTP POST →

X-Hub-Signature-256

X-GitHub-Event: push

🖥️

내 서버

서명 검증 CI/CD 트리거

서명 검증 (보안 필수!):

expected = HMAC-SHA256(secret, body)
actual = request.headers["X-Hub-Signature-256"]
secure_compare(expected, actual) # true → 정상

주의사항

10초 내 200 OK 반환 필요 (무거운 처리는 백그라운드로)
실패 시 GitHub가 자동 재시도 (최대 3회)
Settings → Webhooks에서 전송 로그 확인 가능
로컬 개발 시 ngrok 필요 (공개 URL이 없으므로)

동작 흐름

Repository Settings에서 Webhook URL + Secret 등록

개발자가 git push 실행 (또는 PR 생성, Issue 등)

GitHub가 등록된 URL로 HTTP POST 전송 (JSON payload)

X-Hub-Signature-256 헤더로 HMAC-SHA256 서명 포함

수신 서버가 서명 검증 후 이벤트 처리 (CI/CD 트리거 등)

서버가 200 OK 반환 (10초 내, 실패 시 GitHub 재시도)

장점

✓ 설정이 매우 간단
✓ 이벤트 종류 세밀하게 선택 가능
✓ 실패 시 자동 재시도
✓ GitHub UI에서 전송 로그 확인 가능

단점

✗ 공개 URL 필수 (로컬 개발 시 ngrok 필요)
✗ 10초 타임아웃 (무거운 처리는 비동기로)
✗ 서명 검증 구현 필요
✗ 이벤트 순서 보장 안 됨

사용 사례

CI/CD 자동 빌드 (Jenkins, GitHub Actions) Slack/Discord 알림 자동 배포 트리거 코드 리뷰 봇

기반 아키텍처

🪝

Webhook

이벤트 발생 시 HTTP 콜백

→