웹훅

1. 웹훅 서버 방화벽 안내

웹훅을 정상적으로 수신하려면 가맹점 서버에서 NHN KCP 웹훅 서버 IP의 접근을 허용해야 합니다.
방화벽 또는 보안 장비를 사용하는 경우 아래 IP 정보를 기준으로 INBOUND/OUTBOUND 통신을 허용하세요.

2. 웹훅 이벤트 등록하기

가맹점 서버의 웹훅 페이지가 NHN KCP 파트너관리자에 미리 등록되어 있어야 실 거래 건에 대해 노티 처리가 가능합니다.
아래와 같이 웹훅 URL을 등록하면 결제 상태 변경이 발생했을 때 설정한 웹훅 URL로 웹훅 이벤트가 전송됩니다.

단, Webhook 주소가 HTTPS로 시작하지 않을 경우 이벤트가 발송되지 않을 수 있으니 유의하세요.

3. 웹훅 수신 성공 및 재전송 정책

가맹점 서버가 웹훅 데이터를 정상 수신한 경우, NHN KCP에 0000 응답을 반환해야 합니다.
0000 응답이 반환되지 않거나 통신이 실패하면 웹훅 전송 실패로 처리됩니다.

최초 웹훅 전송이 실패하면 NHN KCP에서 최대 10회까지 웹훅을 재전송합니다.
재전송 중 가맹점에서 result 값이 "0000"으로 응답되면 재전송은 즉시 중단됩니다.

4. 웹훅 데이터 Hash 검증 방법

NHN KCP 웹훅 데이터의 위·변조 여부를 확인할 수 있도록 검증키를 이용해 HMAC-SHA256 해시 검증 기능을 제공합니다.

NHN KCP는 해시 데이터(hash_data)를 생성하고, 이를 웹훅 데이터에 포함하여 전달합니다.
가맹점은 수신한 웹훅 데이터의 주요 필드와 가맹점의 검증키를 조합하여 해시 처리한 후,
전달받은 해시 데이터(hash_data)와 비교하여 데이터의 위·변조 여부를 검증할 수 있습니다.

웹훅 검증키 발급 및 설정 방법

웹훅 검증키란? 웹훅 데이터의 해시 값을 생성하고 검증하는 데 사용되는 가맹점별 고유 키입니다.

최초 검증키는 NHN KCP가 발급하며, 웹훅URL 설정(new) 메뉴에서 이용 동의 시 웹훅 검증키 관리 메뉴에서 확인 및 사용이 가능합니다.
(NHN KCP 파트너관리자 > 기술관리센터 > 웹훅(Webhook)관리 > 웹훅 검증키 관리)

해시 검증에는 파트너관리자에서 조회한 운영 검증키를 사용해야 합니다.

발급된 검증키는 가맹점이 안전하게 보관 및 관리해야 하며, 유출 또는 분실한 경우 다른 검증키로 변경 후 사용해 주세요.

해시 데이터 생성 방식

해시 데이터는 웹훅으로 전달받은 데이터를 활용하여 아래와 같이 지정된 필드를 순서대로 조합하고, 마지막에 검증키를 추가한 문자열에 HMAC-SHA256 해시 알고리즘을 적용하여 생성합니다.
결제수단별 해시 대상 데이터가 상이하니, 아래 내용을 참고하세요.

가상계좌 입금/입금취소 해시 대상데이터

site_cd + "^" + tno + "^" + ordr_idxx + "^" + account + "^" + ipgm_mnyx + "^" + noti_id + "^" + ipgm_time + "^" + tx_cd + "^" + op_cd + "^" + 발급받은 검증키 입력

계좌이체, 가상계좌 에스크로 해시 대상데이터

site_cd + "^" + tno + "^" + order_no + "^" + tx_tm + "^" + tx_cd + "^" + 발급받은 검증키 입력

HMAC-SHA256 함수를 사용하여 해시 데이터 생성

// HMAC-SHA256 해시 함수
public String f_get_hmac_sha256( String data, String key )
{
            Mac mac = Mac.getInstance( "HmacSHA256" );
            mac.init( new SecretKeySpec( key.getBytes( "EUC-KR" ), "HmacSHA256" ) );
            byte[] digestBytes = mac.doFinal( data.getBytes( "EUC-KR" ) );

            StringBuilder sb = new StringBuilder();
            for ( byte b : digestBytes )
            {
                sb.append( String.format( "%02X", b ) );
            }
            return sb.toString();
}

String VERIFY_KEY = "발급받은 검증키 입력";	// KCP 발급 검증키
String plain_data = "해시 대상데이터를 조합한 문자열 입력"

String make_hash_data = f_get_hmac_sha256( plain_data, VERIFY_KEY );