실제 결제 플로우를 통해 웹훅 수신을 테스트하고, 안정성 및 보안을 검증하는 실용 가이드입니다.

본격적인 테스트 전에, 웹훅을 수신하고 디버깅할 환경을 준비합니다.

• 웹훅 URL 등록 완료: 등록 가이드를 참고하여 테스트하려는 이벤트(card, vbank 등)의 URL을 미리 등록해야 합니다.
• 웹훅 엔드포인트 서버 실행 중: 웹훅을 수신할 가맹점 서버가 실행 상태여야 합니다.
• 결제창 연동 완료: 테스트 결제를 진행할 수 있는 결제창이 준비되어 있어야 합니다.

# 1. ngrok 설치 (macOS, Homebrew 기준)
brew install ngrok

# 2. 로컬 서버(예: 3000번 포트)에 터널 생성
ngrok http 3000

Forwarding   https://<랜덤 주소>.ngrok-free.app -> http://localhost:3000

위 Forwarding 주소(https://...)를 복사하여 웹훅 URL로 등록하면, 로컬 환경에서 웹훅을 수신할 수 있습니다.

서버를 직접 구현하기 전에 웹훅의 데이터 구조나 헤더를 확인하고 싶을 때 유용합니다.

1. webhook.site 접속하여 고유 URL을 복사합니다.
2. 복사한 URL을 NICEPAY 웹훅 URL로 등록합니다.
3. 테스트 결제를 진행하면, 해당 사이트의 웹 UI에서 실시간으로 수신된 웹훅 요청을 모든 내용(Header, Body)과 함께 확인할 수 있습니다.

가장 중요한 보안 절차입니다. 모든 시나리오 테스트에 앞서, Signature 검증 로직을 최우선으로 구현해야 합니다.

Signature 검증은 수신한 웹훅이 NICEPAY가 보낸 원본 요청이 맞는지, 중간에 데이터가 위변조되지는 않았는지 확인하는 과정입니다. 이 절차 없이는 웹훅을 신뢰할 수 없습니다.

웹훅 이벤트(status)의 종류에 따라 Signature를 생성하는 필드 조합이 달라집니다.

SecretKey 정보 검증에 사용되는 secretKey는 가맹점 관리자에 등록된 48자의 SecretKey 전체를 의미합니다.

핵심 검증 로직이 준비되었다면, 이제 시나리오별로 웹훅을 테스트합니다.

1. 결제 진행: 샌드박스 결제창에서 아래 테스트 카드로 결제를 진행합니다.
   • 카드번호: 5465-2100-0000-0003
   • 유효기간: 25/12
   • CVC: 123
2. 웹훅 수신: 결제 완료 시 status: "paid"인 웹훅이 수신됩니다.
3. 검증:
   • 수신된 웹훅의 Signature가 위 2단계에서 구현한 로직에 따라 검증되는지 확인합니다.
   • tid, orderId, amount 등 주요 정보가 예상과 일치하는지 확인합니다.

가상계좌는 **'발급'**과 '입금' 시점에 각각 웹훅이 전송됩니다.

1. 1차 웹훅 (발급):
   • 테스트 방법: 가상계좌 결제를 시도하여 계좌번호를 발급받습니다.
   • 수신 내용: status: "ready"인 웹훅이 수신되며, vbank 객체에 계좌 정보가 포함됩니다.
   • 검증: ready 상태에 맞는 Signature 공식을 사용하여 검증되는지 확인합니다.
2. 2차 웹훅 (입금):
   • 테스트 방법: 실제 입금 없이, 샌드박스 입금을 시뮬레이션합니다.

     샌드박스 가맹점관리자 로그인 → '테스트 > 가상계좌 입금통보' 메뉴에서 발급된 웹훅의 tid를 입력하여 입금을 강제 실행할 수 있습니다.

   • 수신 내용: status: "paid"인 웹훅이 수신되며, paidAt 필드가 채워져 있습니다.
   • 검증: paid 상태에 맞는 Signature 공식을 사용하여 검증되는지 확인합니다.

1. 결제 진행: 먼저 카드 결제를 성공시켜 tid를 확보합니다.
2. 취소 API 호출: 해당 tid로 결제 취소 API를 호출합니다.
3. 웹훅 수신: status: "cancelled"인 웹훅이 수신됩니다.
4. 검증:
   • cancelled 상태에 맞는 Signature 공식을 사용하여 검증되는지 확인합니다.
   • cancelAmt가 요청한 취소 금액과 일치하는지 확인합니다.

모든 테스트를 마친 후, 아래 항목을 최종적으로 점검합니다.

• 카드 결제 웹훅 (paid)
• 가상계좌 발급 웹훅 (ready)
• 가상계좌 입금 웹훅 (paid)
• 결제 취소 웹훅 (cancelled)

• 모든 웹훅에 대해 Signature 검증을 수행하는가?
• 모든 웹훅 수신 시 **200 OK**를 즉시 응답하는가?
• 1-Transaction 방식의 경우, 중복 처리 방지 로직이 정상 동작하는가?
• DB에 저장된 주문 정보(금액, 상태 등)가 웹훅 내용과 일치하게 업데이트되는가?

• 1-Transaction 웹훅 & 승인금액검증: 1-Transaction 방식을 사용한다면 반드시 읽어야 할 심화 가이드
• 웹훅 거래통보 명세: 웹훅으로 전달되는 모든 필드에 대한 상세 명세