Webhook은 한 애플리케이션(또는 서비스)이 다른 애플리케이션에게 특정 이벤트가 발생했음을 실시간으로 알려주기 위해 사용하는 “푸시 방식”의 HTTP 콜백 메커니즘입니다. 일반적으로 이벤트 발생 시 제공자(provider)가 미리 등록된 URL(수신자, 즉 webhook 엔드포인트)로 HTTP 요청을 보내고, 수신자는 그 요청의 내용을 처리합니다. 주요 특징 - 푸시 기반: 수신자가 주기적으로 상태를 조회(polling)하지 않고, 이벤트 발생 시 제공자가 즉시 알림을 보냄. - HTTP 요청: 보통 POST 요청으로 JSON(또는 form-encoded, XML 등) 페이로드를 전송. - 이벤트 중심: 결제 성공, 주문 생성, 코드 푸시 등 특정 이벤트에 대해 트리거됨. - 비동기성: 즉시 응답(일반적으로 2xx)을 반환하면 제공자는 성공으로 간주하고, 실패 시 재시도 정책을 사용함. 일반 동작 흐름 1. 수신자는 자신의 엔드포인트 URL을 제공자에 등록(또는 설정)한다. 2. 제공자 시스템에서 특정 이벤트가 발생하면, 해당 URL로 HTTP POST 요청을 보낸다. 3. 수신자는 요청을 받아서 유효성 검사 및 비즈니스 로직을 수행한 뒤 2xx 응답을 반환한다. 4. 제공자는 비-2xx 응답 또는 타임아웃이 발생하면 일정한 재시도 정책을 적용할 수 있다. 보안 및 신뢰성 고려사항 - 서명 검증: 페이로드에 대한 HMAC 서명 또는 전용 토큰을 헤더에 포함하여 발신자를 검증. - TLS(HTTPS) 사용: 전송 중 데이터 보호. - IP 화이트리스트: 제공자가 고정 IP를 제공하면 수신 측에서 허용 목록에 추가. - 페이로드 검증: 스키마와 필드 유효성 검사. - 재시도/중복 처리: 재시도가 발생할 수 있으므로 idempotency(중복 처리 방지) 로직 필요. - 레이팅/큐잉: 대량 이벤트에 대비한 큐 처리 또는 백프레스처 설계. 장점과 단점 - 장점: 실시간성, 효율성(불필요한 폴링 감소), 간단한 통합 모델. - 단점: 보안과 신뢰성 관리 필요, 수신자의 엔드포인트 가용성 문제, 이벤트 흐름 제어(속도 제한) 어려움. 실제 사용 예 - 결제 서비스(예: 결제 완료 알림) - 코드 호스팅 플랫폼(예: 푸시나 풀 리퀘스트 이벤트) - CI/CD 파이프라인 트리거 - 채팅봇, CRM, 주문/배송 알림 등 테스트 및 개발 팁 - 로컬 개발 시 ngrok 같은 도구로 로컬 엔드포인트를 외부에서 접근 가능하게 만들기. - 제공자 대시보드에서 재전송 기능이나 최근 전달 로그 확인. 요약하면, webhook은 서비스 간 이벤트를 실시간으로 전달하는 간단한 HTTP 기반의 콜백 메커니즘으로, 실시간 통합이 필요할 때 많이 사용되며 보안·중복 처리·가용성에 대한 추가 고려가 필요합니다.
