웹훅(webhook)
웹훅(Webhook) 연동 가이드
웹훅이란?
특정 이벤트 발생 시, 설정된 URL로 HTTP POST 요청을 보내는 알림 시스템
주기적으로 상태를 조회하는 폴링(Polling) 방식보다 효율적
결제 상태가 변경될 때마다 고객사 서버로 자동 알림을 보냄
왜 웹훅이 필요한가요?
상황
웹훅이 없으면
웹훅이 있으면
✅ 정상 결제
클라이언트 응답으로 처리
웹훅으로도 다시 확인, 중복 처리 방지
⚠️ 네트워크 불안정
결제 완료 응답 수신 실패 가능
웹훅으로 서버 간 통신으로 복구
⚠️ 브라우저 종료/새로고침
결제 후 응답 누락
웹훅이 서버에 다시 알려줌
✅ 수동 취소 (관리자)
수동으로 조회해야 인지
웹훅이 자동 알림으로 전송
💡 결론: 반드시 연동 권장! 실시간 동기화 + 장애 복구 가능
웹훅 이벤트 종류
이벤트 설명
상태 코드 (status)
결제가 승인되었을 때
paid
결제가 취소된 경우
cancel
웹훅 동작 흐름도
고객사 서버 구현 포인트
웹훅을 보내면 HTTP 200 OK 로 응답하도록 구현
실패 시, 서버가 최대 24시간 동안 재시도 (재시도 주기: 10분 → 30분 → 1시간 …)
반드시 수신한 이벤트 내용을 로그로 저장
이벤트 데이터 검증 (예: signature 검증) 필수!=
보안 권장사항
재시도 정책
상황
설명
최초 요청 실패
최초 요청 후 HTTP 200 응답 없으면 재시도
재시도 횟수
최대 24시간 동안, 간격 증가 (10분 → 30분 → 1시간 등)
성공 시
즉시 종료
고객사 서버 다운 시
재시도 중 서버 복구 후 응답 시, 결제 정보 복구 가능
Last updated