🐙
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가 자동으로 재시도합니다.
구조 다이어그램
사전 설정
👤
리포지토리 소유자
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이 없으므로)
동작 흐름
1
Repository Settings에서 Webhook URL + Secret 등록
2
개발자가 git push 실행 (또는 PR 생성, Issue 등)
3
GitHub가 등록된 URL로 HTTP POST 전송 (JSON payload)
4
X-Hub-Signature-256 헤더로 HMAC-SHA256 서명 포함
5
수신 서버가 서명 검증 후 이벤트 처리 (CI/CD 트리거 등)
6
서버가 200 OK 반환 (10초 내, 실패 시 GitHub 재시도)
장점
- ✓ 설정이 매우 간단
- ✓ 이벤트 종류 세밀하게 선택 가능
- ✓ 실패 시 자동 재시도
- ✓ GitHub UI에서 전송 로그 확인 가능
단점
- ✗ 공개 URL 필수 (로컬 개발 시 ngrok 필요)
- ✗ 10초 타임아웃 (무거운 처리는 비동기로)
- ✗ 서명 검증 구현 필요
- ✗ 이벤트 순서 보장 안 됨
사용 사례
CI/CD 자동 빌드 (Jenkins, GitHub Actions)
Slack/Discord 알림
자동 배포 트리거
코드 리뷰 봇