웹훅(Webhook)이란?
웹훅(Webhook)은 특정 이벤트가 발생했을 때 자동으로 지정한 URL로 데이터를 보내주는 방식입니다. "알림 받을 주소를 미리 등록해두면, 변화가 생길 때 알려준다"라고 이해하면 됩니다.
쉽게 이해하기
비유로 이해하기
폴링(Polling) = 매 시간마다 택배 기사에게 전화해서 "내 택배 어디쯤이야?"
웹훅(Webhook) = 택배 기사가 "도착하면 문자 드릴게요" 하고, 도착하면 알아서 연락
폴링 vs 웹훅
폴링 (Polling)
- 주기적으로 "변경 있어?" 물어봄
- 변경 없어도 계속 요청
- 서버 부하 증가
- 실시간성 떨어짐
웹훅 (Webhook)
- 변경 생기면 알아서 알려줌
- 필요할 때만 데이터 전송
- 서버 부하 적음
- 실시간 반응 가능
웹훅 동작 원리
1. 웹훅 URL 등록
이벤트 발생 시 알림을 받을 URL을 미리 등록합니다. 송장번호와 함께 웹훅 URL을 등록하면, 배송 상태 변경 시 해당 URL로 알림이 전송됩니다.
2. 이벤트 발생
배송 상태가 변경되면 시스템이 이를 감지합니다.
3. 웹훅 호출
등록된 URL로 변경된 정보를 POST 요청으로 보내줍니다.
// myshop.com/webhook/delivery로 전송되는 데이터
{
"event": "tracking.polled",
"requestId": "req_xxx",
"timestamp": "2024-01-15T14:30:00.000Z",
"summary": {
"total": 2,
"delivered": 1,
"active": 1,
"hasChanges": true
},
"items": [
{
"courierCode": "cj",
"trackingNumber": "1234567890",
"currentStatus": "DELIVERED",
"previousStatus": "OUT_FOR_DELIVERY",
"hasChanged": true,
"isDelivered": true,
"trackingData": {
// UnifiedTrackingResponse 구조
}
}
],
"metadata": {
// 구독 시 등록한 메타데이터 (예: 주문번호)
}
}4. 처리
내 서버에서 이 데이터를 받아서 원하는 작업을 수행합니다.
// Express.js 웹훅 수신 예시
app.post('/webhook/delivery', (req, res) => {
const { event, items } = req.body;
// 이벤트 타입 체크
if (event !== 'tracking.polled' && event !== 'tracking.completed') {
return res.status(400).send('Unknown event');
}
for (const item of items) {
const { trackingNumber, currentStatus, previousStatus, isDelivered } = item;
// 배송 완료 시 처리
if (isDelivered) {
// 주문 상태를 "배송완료"로 변경
updateOrderStatus(trackingNumber, '배송완료');
// 고객에게 카카오톡 알림 발송
sendKakaoNotification(item);
}
}
// 200 응답 필수
res.status(200).json({ received: true });
});웹훅 활용 예시
- 배송 알림 - 배송 출발/완료 시 고객에게 알림
- 주문 상태 업데이트 - 쇼핑몰 주문 상태 자동 변경
- 결제 확인 - 결제 완료 시 주문 처리 시작
- GitHub - 코드 푸시 시 자동 배포
- Slack - 특정 이벤트 발생 시 채널에 알림
웹훅 구현 시 주의사항
- HTTPS 필수 - 보안을 위해 HTTPS URL만 허용
- 빠른 응답 - 3초 내로 응답해야 함 (긴 작업은 백그라운드 처리)
- 멱등성 - 같은 요청이 여러 번 와도 동일한 결과
- 인증 - 서명 검증으로 위조 요청 방지