깃허브 웹후크 이해: 프로젝트 요청 시 이메일 알림(Node.js)

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발, DevOps

대상자

• Node.js 및 GitHub 웹후크 인프라 구축에 관심 있는 개발자
• 보안 검증 및 이메일 알림 시스템 구현을 학습하고자 하는 초급~중급 개발자
• HMAC, Nodemailer, Render 배포 플랫폼 사용 경험을 확보하고자 하는 개발자

핵심 요약

• HMAC과 공유 비밀키를 사용한 웹후크 인증을 통해 GitHub의 요청 정체성 검증
• Nodemailer + Gmail SMTP를 활용한 이메일 알림 시스템 구현
• Render 플랫폼을 통해 로컬 서버 대신 외부 액세스 가능한 웹후크 엔드포인트 생성

섹션별 세부 요약

1. 웹후크 보안 원리

• HMAC (Hash-based Message Authentication Code)을 사용하여 요청 무결성 및 발신자 인증
• X-Hub-Signature-256 헤더에 SHA-256 해시 값 포함
• 공유 비밀키를 기반으로 요청 본문과 HMAC 서명 비교

2. Express에서의 요청 처리

• express.json() 미들웨어의 verify 옵션을 통해 원본 요청 본문(rawBody) 캡처
• HMAC 서명 재계산 시 해석된 본문 대신 rawBody 사용 필수
• crypto.createHmac("sha-256", secret)로 서명 생성 및 시간 공격 방지 비교

3. 이메일 알림 구현

• Nodemailer 모듈을 사용한 Gmail SMTP 설정
• 2FA 활성화 시 App Password 사용 권장
• transporter.sendMail() API로 프로젝트 요청 이벤트 시 이메일 전송

4. 웹후크 엔드포인트 배포

• Ngrok 또는 Render 사용을 통해 로컬 서버 외부 노출
• Render 플랫폼의 무료 계층 활용, 간편한 배포 프로세스
• GitHub 웹후크 설정 시 Render URL 엔드포인트 등록

결론

• HMAC 인증과 Nodemailer 이메일 알림은 GitHub 웹후크 안전한 처리의 핵심
• Render 같은 클라우드 플랫폼 활용으로 실무적 배포 가능
• 로컬 서버 대신 외부 액세스 가능한 엔드포인트 생성이 필수적