노티(Webhook) 테스트 가이드

노티 테스트, 왜 다른가요?

일반적인 API 테스트는 가맹점에서 PG사로 요청을 보내고 응답을 받는 구조예요. 하지만 노티(결과통보) 는 반대로 PG사에서 가맹점으로 요청을 보내는 구조이기 때문에 테스트 방법이 달라요.

노티를 수신하려면 가맹점 서버가 외부에서 접근 가능한 URL 을 가지고 있어야 해요. 로컬 개발 환경에서는 localhost가 외부에서 접근 불가능하기 때문에 별도의 설정이 필요합니다.

테스트 환경 구성하기

방법 1: webhook.site 활용 (권장)

webhook.site는 웹훅 테스트를 위한 무료 서비스예요. 별도 설치 없이 바로 사용할 수 있어서 가장 간편해요.

사용 방법

1. webhook.site에 접속합니다
2. 자동으로 생성된 고유 URL을 복사합니다 (예: https://webhook.site/abc123...)
3. 결제 요청 시 notiUrl 파라미터에 해당 URL을 설정합니다
4. 테스트 결제를 진행합니다
5. webhook.site 페이지에서 수신된 노티 데이터를 확인합니다

장점

• 설치 불필요, 즉시 사용 가능
• 수신된 요청의 헤더, 바디를 상세히 확인 가능
• 응답 커스터마이징 가능 (Edit 버튼)

단점

• 실제 비즈니스 로직 테스트 불가
• 무료 버전은 URL 유효 기간 제한

방법 2: ngrok 활용 (로컬 개발)

ngrok은 로컬 서버를 외부에서 접근 가능하게 터널링해주는 도구예요. 실제 비즈니스 로직까지 테스트하려면 이 방법을 사용하세요.

설치 및 실행

# macOS (Homebrew)
brew install ngrok

# Windows (Chocolatey)
choco install ngrok

# 또는 공식 사이트에서 직접 다운로드
# https://ngrok.com/download

사용 방법

# 1. 로컬 서버 실행 (예: 3000번 포트)
npm run dev

# 2. 새 터미널에서 ngrok 실행
ngrok http 3000

# 3. 발급된 HTTPS URL 확인
# Forwarding https://abc123.ngrok.io -> http://localhost:3000

발급된 URL을 notiUrl로 사용합니다:

https://abc123.ngrok.io/api/payment/noti

장점

• 실제 비즈니스 로직 테스트 가능
• 로컬 디버깅 환경에서 노티 수신 확인

단점

• ngrok 설치 필요
• 무료 버전은 URL이 매번 변경됨

방법 3: 스테이징 서버 활용

개발/스테이징 서버가 외부에서 접근 가능하다면, 해당 서버의 노티 수신 엔드포인트를 notiUrl로 설정하여 테스트할 수 있어요.

https://dev.example.com/api/payment/noti

테스트 체크리스트

노티 연동 시 아래 항목들을 반드시 확인하세요.

필수 확인 항목

• 해시 검증: pktHash 값이 서버에서 계산한 해시와 일치하는지
• 응답 형식: Plain Text로 OK만 반환하는지 (공백, 줄바꿈 없이)
• 상태 코드 처리: outStatCd에 따른 분기 처리가 정상 작동하는지
• 중복 처리 방지: 동일 노티를 여러 번 수신해도 멱등성이 보장되는지

가상계좌 추가 확인 항목

가상계좌는 여러 종류의 노티가 발생합니다:

• 채번 노티 (outStatCd: 0051, bizType: A0): 계좌 발급 시 처리
• 입금 노티 (outStatCd: 0021, bizType: B1): 실제 입금 완료 시 처리
• 채번 취소 노티 (outStatCd: 0031, bizType: A2): 채번 취소 시 처리

자주 발생하는 문제

노티가 수신되지 않아요

1. notiUrl 설정 확인: 결제 요청 시 notiUrl 파라미터가 올바르게 설정되었는지 확인
2. URL 접근성 확인: 설정한 URL이 외부에서 접근 가능한지 확인
3. 방화벽 확인: PG사 서버 IP가 방화벽에서 차단되지 않았는지 확인
4. HTTPS 확인: 운영 환경에서는 HTTPS URL만 허용될 수 있음

노티가 계속 재전송돼요

1. 응답 형식 확인: OK 외의 문자(공백, 줄바꿈 포함)가 응답에 포함되지 않았는지 확인
2. 응답 시간 확인: 타임아웃 전에 응답을 반환하는지 확인 (권장: 5초 이내)
3. 서버 로그 확인: 요청 처리 중 예외가 발생하지 않는지 확인

해시 검증이 실패해요

1. 필드 순서 확인: 해시 생성 시 필드 조합 순서가 올바른지 확인
2. 인코딩 확인: UTF-8 인코딩으로 해시를 생성하는지 확인
3. 해시키 확인: 테스트/운영 환경에 맞는 해시키를 사용하는지 확인

참고 문서

• 결과통보 URL, 왜 필수일까? - notiUrl의 역할과 구현 방법
• 결제 데이터 암호화 가이드 - 해시 생성 원리와 보안 가이드

연동 중 문의사항은 기술지원팀으로 연락 주세요.

더 궁금한 내용이 있나요?

FAQ

기술지원이 필요한가요?

pg_dev@hecto.co.kr

코드 샘플

HectoFinancial GitHub