# 문제 해결

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

문서: https://sendwich.kr/docs/troubleshooting/

## 문자 전송 후 pending 유지

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

대시보드의 **인증 체험**에서 새 시도를 진행해 수신 상태를 확인할 수 있습니다. 문제가 계속되면 [문의](https://sendwich.kr/dashboard/#support)에 인증 ID, 발생 시각, 요청 ID를 전달합니다.

## API 연동 중 URL 검증 오류

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

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

## 팝업 차단

클릭 이벤트에서 빈 팝업을 열고, 비동기 서버 요청이 끝나면 해당 창의 주소를 변경합니다. 팝업을 열 수 없으면 같은 탭에서 이동하도록 처리합니다. [팝업 예제](https://sendwich.kr/docs/verification-window/)를 참고합니다.

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

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

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

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

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

## 웹훅 미수신

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

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

## 웹훅 서명 불일치

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

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

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

## 기존 테스트 프로젝트

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