Translated from the English article and reviewed by a person. Read the English original
Developer
ngrok을 사용한 Cams 콜백 URL 로컬 테스트
연동을 프로덕션 환경에 배포하기 전에, 터널링 도구를 사용하여 개발용 컴퓨터에서 Cams API 콜백을 직접 테스트할 수 있습니다. 이 가이드는 단계별 설정 방법을 안내합니다.
터널이 필요한 이유
콜백 및 웹훅 요청은 인터넷을 통해 Cams 플랫폼에서 발생합니다. 로컬 컴퓨터에서 실행되는 애플리케이션은 방화벽 또는 NAT 네트워크 뒤에 있기 때문에 이러한 요청을 직접 받을 수 없습니다.
터널링 서비스는 들어오는 요청을 로컬 애플리케이션으로 전달하는 보안 공용 엔드포인트를 생성합니다.
장점
- 배포 전에 콜백 테스트
- 웹훅 페이로드를 실시간으로 디버깅
- 로컬에서 요청 처리 검증
- 개발 및 배포 시간 단축
권장 터널링 도구

ngrok 설정 (권장)
설치
- https://ngrok.com에 접속합니다
- 운영 체제에 맞는 버전을 다운로드합니다.
- 실행 파일을 압축 해제하고 설치합니다.
- 무료 계정을 생성합니다(선택 사항이지만 권장).
- AuthToken을 생성합니다.
- AuthToken을 설정합니다.
ngrok config add-authtoken YOUR_AUTHTOKEN
터널 시작
ngrok이 이미 설정되어 있는 경우:
ngrok http 3000
3000을 애플리케이션의 포트 번호로 바꾸세요.
출력 예시
Forwarding https://abc123.ngrok-free.app -> http://localhost:3000
Your application is now accessible through the public HTTPS URL.
대안: Cams 콜백 테스트 도구 사용
Cams에서 제공하는 콜백 테스트 유틸리티를 사용할 수도 있습니다.
- 아래 링크를 사용하여 도구를 설치하고 압축을 해제합니다.
https://developer.camsbiometrics.com/setup/ngrok-helper-kit.rar app.properties파일을 편집합니다.- 다음을 설정합니다:
ngrok.auth.token=
ngrok.tunnel.url= - check_ngrok.bat을 실행합니다.
이 유틸리티는 터널을 자동으로 설정하여 로컬 콜백 테스트를 간편하게 해 줍니다.
콜백 연동 설정
1단계: 로컬 애플리케이션 시작
2단계: 터널 시작
3단계: 콜백 테스트
샘플 테스트 이벤트를 발생시키고 다음 사항을 확인합니다:
- 애플리케이션이 콜백 요청을 수신합니다.
- 요청 페이로드가 성공적으로 처리됩니다.
- 애플리케이션 로그에 오류가 나타나지 않습니다.
- 터널 대시보드에서 요청을 확인할 수 있습니다.
모범 사례
- 가능한 경우 HTTPS 콜백 URL을 사용하세요.
- 테스트 중에는 터널을 계속 활성 상태로 유지하세요.
- 요청 유효성 검사를 위해 애플리케이션 로그를 검토하세요.
- 엔드포인트가 예상되는 HTTP 응답 코드를 반환하는지 확인하세요.
- 프로덕션 환경으로 옮기기 전에 오류 처리 시나리오를 테스트하세요.
주요 참고 사항
- 무료 ngrok URL은 터널이 재시작될 때마다 변경됩니다.
- 유료 ngrok 요금제는 예약된 도메인과 사용자 지정 서브도메인을 지원합니다.
- 임시 터널은 개발 및 테스트 목적으로만 사용해야 합니다.
결론
터널링 서비스를 통해 로컬 서버를 외부에 노출하는 것은 애플리케이션을 배포하기 전에 콜백 URL을 테스트하는 가장 빠른 방법입니다. ngrok, Cloudflare Tunnel, localhost.run 중 어떤 것을 사용하든, 이 방법을 통해 실시간 콜백 요청을 수신하고 로컬 개발 환경에서 연동을 검증할 수 있습니다.
위의 단계를 따르면 개발에서 프로덕션 배포로의 원활한 전환에 도움이 됩니다.
Was this article helpful?