문서/운영하기

문제 해결

문자 인증, 팝업 연결, 웹훅 수신 오류 해결

문자 전송 후 pending 유지#

항목	확인 사항
수신 번호	최신 인증 응답의 `destination`과 일치하는지
문자 본문	`sms_text`와 일치하며 중간 공백·추가 문장이 없는지
발신 번호	`match`에서 지정한 번호의 SIM으로 전송했는지
유효시간	SMS 수신 처리 전에 `expires_at`이 지났는지
조회 대상	문자를 전송한 인증의 ID로 조회했는지

대시보드의 인증 체험에서 새 시도를 진행해 수신 상태를 확인할 수 있습니다. 문제가 계속되면 문의에 인증 ID, 발생 시각, 요청 ID를 전달합니다.

API 연동 중 URL 검증 오류#

API 직접 연동에서는 생성 요청의 parent_origin, return_url을 생략합니다. 두 필드를 사용한다면 프로젝트에 등록한 주소와 일치해야 합니다.

웹훅 수신 URL은 별도 설정입니다. 웹훅을 사용하는 경우에만 서비스 서버의 HTTPS 주소를 등록합니다.

팝업 차단#

클릭 이벤트에서 빈 팝업을 열고, 비동기 서버 요청이 끝나면 해당 창의 주소를 변경합니다. 팝업을 열 수 없으면 같은 탭에서 이동하도록 처리합니다. 팝업 예제를 참고합니다.

문자 앱의 본문 자동 입력 실패#

화면에 표시된 받는 번호와 인증 문자를 복사해 전송합니다. 직접 만든 화면에도 번호와 문자 복사 기능을 제공합니다.

인증 완료 후 원래 화면에 미반영#

생성 요청에 parent_origin이 포함되어 있고 프로젝트 등록값과 일치하는지 확인합니다. postMessage의 수신 출처는 https://id.it.kr입니다.

팝업 알림이나 복귀 URL을 받은 뒤 서버에서 결과를 조회해야 합니다. 팝업 연결이 끊기거나 알림이 유실된 경우에도 API 조회·웹훅으로 최종 상태를 확인할 수 있습니다.

웹훅 미수신#

웹훅을 저장한 후 생성한 인증인지 확인합니다. 대시보드의 전송 내역에서 HTTP 상태와 시도 횟수를 확인할 수 있습니다.

수신 주소는 외부에서 접근 가능한 HTTPS 443 포트여야 합니다. 301, 302 리디렉션은 지원하지 않습니다.

웹훅 서명 불일치#

JSON 파싱 전의 원본 본문 바이트, 서버 시각, whsec_ 접두사를 포함한 서명 키를 확인합니다. 키를 교체한 경우 기존 인증의 이벤트에는 이전 키를 사용해야 합니다. 서명 검증을 참고합니다.

예상보다 많은 호출 사용량#

조회·실패·재시도도 각각 API 호출로 집계됩니다. 주기적인 조회 간격과 종료 조건을 확인합니다. 429 monthly_call_limit은 월 허용량을 소진한 상태이므로 다음 집계 월이나 요금제 변경 후 재개합니다. 자세한 집계 기준은 요금제와 사용량에서 확인할 수 있습니다.

기존 테스트 프로젝트#

기존 테스트 프로젝트와 결과는 test로 표시되며 시뮬레이션으로 동작합니다. 실제 번호 확인에는 새 SMS 프로젝트의 live 결과를 사용합니다. 공개 데모는 화면 체험용입니다.