웹훅 (Webhook)

웹훅 (Webhook)

웹훅(Webhook)은 한 시스템에서 특정 이벤트가 발생했을 때, 다른 시스템으로 이를 자동으로 알려주는 방식이다.

---

특징

웹훅은 요청(Request)을 보내는 시점을 이벤트 발생 시점에 맡기는 구조이다.
즉, 서버가 이벤트를 감지하면 미리 지정된 URL로 HTTP 요청(보통 POST) 을 전송한다.
이 요청에는 해당 이벤트에 대한 데이터(payload)가 포함된다.
이를 통해 수신 서버는 별도의 요청 없이도 실시간으로 정보를 전달받을 수 있다.

---

동작 원리

1. 수신 URL 등록
   먼저, 웹훅을 받을 서버(수신자)는 이벤트를 받을 URL을 제공한다.
2. 이벤트 발생 감지
   송신 서버는 내부에서 특정 이벤트(예: 결제 완료, 회원 가입, 커밋 생성 등)가 발생하면 이를 감지한다.
3. HTTP 요청 전송
   송신 서버가 해당 이벤트 정보를 JSON 형태로 수신 서버의 URL로 전송한다.
4. 수신 서버 처리
   수신 서버는 요청 본문을 읽어 이벤트 데이터를 저장하거나 추가 로직을 실행한다.

예시

예를 들어, 결제 서비스인 토스페이먼츠를 사용할 때 사용자가 결제를 완료하면 토스 서버는 개발자의 서버에 다음과 같은 요청을 보낸다.

POST /api/payment/webhook
Content-Type: application/json

{
  "paymentKey": "pay_12345",
  "status": "DONE",
  "amount": 10000
}

이 요청을 받은 서버는 해당 정보를 DB에 기록하거나 결제 완료 처리를 수행한다.
이처럼, 웹훅은 실시간 이벤트 알림 역할을 한다.

---

폴링(Polling)과의 차이점

구분	폴링(Polling)	웹훅(Webhook)
방식	일정 주기로 서버에 변경 사항을 요청	이벤트 발생 시 즉시 알림
장점	구현이 단순	지연이 적고 효율적
단점	불필요한 요청이 많음	수신 서버를 항상 공개해야 함

---

주요 활용 사례

웹훅은 다양한 웹 서비스에서 자동화된 통신을 위해 널리 사용된다.

• CI/CD (지속적 통합/배포): GitHub/GitLab 같은 코드 저장소에 새로운 코드가 Push되면, 웹훅을 통해 빌드 및 배포 시스템(Jenkins, CircleCI 등)을 자동으로 트리거함
• 결제 알림: 온라인 쇼핑몰에서 결제 완료 이벤트가 발생하면, 웹훅을 통해 재고 관리 시스템이나 회계 시스템으로 데이터가 전송되어 자동으로 처리됨
• 챗봇/알림: Slack, MS Teams 등의 협업 도구에서 새로운 메시지나 특정 시스템 알림이 발생하면 웹훅을 통해 실시간으로 알림을 전달
• 고객 지원: 사용자가 문의를 등록하면, 웹훅을 통해 고객 지원 시스템에 자동으로 지원 티켓이 생성됨

---

구현 시 고려사항

• 보안 검증
  웹훅 요청이 신뢰할 수 있는 서버에서 온 것인지 확인해야 한다.
  일반적으로 서명 검증이나 토큰 인증을 사용한다.
  
• 빠른 응답 처리
  송신 서버는 응답 시간이 느릴 경우 요청을 실패로 판단할 수 있으므로, 비동기 방식으로 처리하는 것이 좋다.
  
• 로그 관리 및 재시도 로직
  네트워크 문제로 수신 실패 시 재시도할 수 있도록 로그를 남기는 것이 바람직하다.