웹훅
웹훅(Webhook) 서비스
NHN KCP에서 결제 상태 변경 이벤트가 발생하면, 사전에 등록한 가맹점 URL로 HTTP 기반 콜백(POST) 요청을 전송하여 해당
이벤트 데이터를 전달합니다. 예를 들어 가상계좌 입금 완료와 같은 이벤트가 이에 해당합니다.
즉, 가맹점이 별도로 상태를 조회하지 않아도 이벤트 발생 시점에 맞춰 NHN KCP가 자동으로 결제 결과를 통보하는 실시간 연동 방식입니다.
웹훅이 필요한 이유
가상계좌는 카드 결제처럼 즉시 승인되는 구조가 아니므로, 구매자가 실제로 입금한 시점에 결제가 완료됩니다.
에스크로는 결제 승인 이후에도 배송시작, 즉시취소 등 다양한 상태 변경 이벤트가 발생합니다.
따라서 가상계좌 입금 완료 여부를 확인하고 에스크로 상태를 동기화하려면 웹훅 연동이 필요합니다.
1. 웹훅 서버 방화벽 안내
웹훅을 정상적으로 수신하려면 가맹점 서버에서 NHN KCP 웹훅 서버 IP의 접근을 허용해야 합니다.
방화벽 또는 보안 장비를 사용하는 경우 아래 IP 정보를 기준으로 INBOUND/OUTBOUND 통신을 허용하세요.
| 항목 | 테스트 | 운영 |
|---|---|---|
| Webhook 서버 IP | 210.122.176.144 | 103.215.144.173 103.215.144.174 210.122.72.173 |
| 연결 방향 | INBOUND/OUTBOUND | INBOUND/OUTBOUND |
2. 웹훅 이벤트 등록하기
가맹점 서버의 웹훅 페이지가 NHN KCP 파트너관리자에 미리 등록되어 있어야 실 거래 건에 대해 노티 처리가 가능합니다.
아래와 같이 웹훅 URL을 등록하면 결제 상태 변경이 발생했을 때 설정한 웹훅 URL로 웹훅 이벤트가 전송됩니다.
단, Webhook 주소가 HTTPS로 시작하지 않을 경우 이벤트가 발송되지 않을 수 있으니 유의하세요.
3. 웹훅 수신 성공 및 재전송 정책
가맹점 서버가 웹훅 데이터를 정상 수신한 경우, NHN KCP에 0000 응답을 반환해야 합니다.
0000 응답이 반환되지 않거나 통신이 실패하면 웹훅 전송 실패로 처리됩니다.
최초 웹훅 전송이 실패하면 NHN KCP에서 최대 10회까지 웹훅을 재전송합니다.
재전송 중 가맹점에서 result 값이 "0000"으로 응답되면 재전송은 즉시 중단됩니다.