지난 [메시지 전송 결과 리포트, 왜 중요하고 어떻게 받을까?] 콘텐츠에서 API 초기 응답과 최종 단말기 전송 결과의 차이점, 그리고 이 최종 결과를 확인하는 방법으로 폴링과 웹훅 방식이 있다는 것을 알아보았습니다. 특히, 실시간으로 메시지 전송 상태를 파악하고 오류 발생 시 즉각적으로 대응해야 하는 서비스라면 웹훅(Webhook) 방식이 훨씬 더 효과적이라는 점도 강조했었죠.
하지만 막상 웹훅을 시스템에 적용하려고 하면, “데이터는 받았는데, 이걸로 뭘 더 할 수 있지?”, “간헐적으로 웹훅 수신이 안 되는 것 같은데, 왜 그런 건가요?”, “다양한 reportCode는 어떻게 다르게 처리해야 하나요?” 와 같은 현실적인 궁금증과 어려움에 직면하게 됩니다.
오늘 비즈고에서는 개발자 여러분의 이러한 ‘진짜’ 궁금증을 해결하고, 웹훅 활용 레벨을 한 단계 높여드리기 위해 자주 묻는 질문(FAQ) 형식으로 웹훅 리포팅을 심층적으로 파헤쳐 드리겠습니다!
⚙️ 웹훅(Webhook) 기본 설정: 시작 전 필수 확인 사항
웹훅 리포팅을 안정적으로 사용하기 위한 첫걸음은 정확한 설정과 환경 준비입니다. 개발자분들이 가장 먼저 확인하고 준비해야 할 핵심 사항들을 Q&A 형식으로 알아보겠습니다.
Q1. 웹훅 수신 URL은 어떻게 준비하고 등록해야 하나요?
A1: 웹훅을 사용하기 위한 첫 단추인 만큼 정확한 설정이 중요합니다. 크게 세 가지 포인트를 기억하시면 됩니다.
✅ URL 엔드포인트 개발
먼저, 고객사 시스템에서 비즈고가 발송하는 웹훅 데이터(HTTP POST, JSON 형식)를 수신하고 처리할 수 있는 공개된 URL 엔드포인트를 준비해야 합니다. 이 엔드포인트는 안정적으로 요청을 처리하고, 아래 설명드릴 정확한 응답을 비즈고 서버로 보내줄 수 있어야 합니다.
✅ URL 등록 절차
준비된 웹훅 수신 URL은 [팀스페이스 > 메시지 발송 > 시스템 발송 > 연동 계정 정보] 메뉴에서 직접 등록하실 수 있습니다.
✅ 방화벽 설정 확인
방화벽을 사용하고 계신다면, 비즈고의 Webhook 서비스 IP들이 반드시 방화벽 허용 목록(화이트리스트)에 추가되어야 합니다. 그렇지 않으면 웹훅 데이터가 방화벽에 의해 차단되어 정상적으로 수신되지 않을 수 있습니다. (IP 주소는 보안 정책상 변경될 수 있으므로, 연동 시 비즈고 담당자 또는 개발자 문서를 통해 최신 정보를 확인해주세요.)
Q2. 웹훅 데이터를 받았는데, 가끔 누락되는 것처럼 느껴져요. 저희 쪽 응답 처리에 문제가 있는 걸까요?
A2. 웹훅 데이터 수신이 불안정하다고 느껴지신다면, 가장 먼저 고객사 서버의 응답 처리 방식을 점검해보시는 것이 좋습니다.
✅ 정확한 성공 응답 전송
비즈고 서버로부터 웹훅 데이터를 정상적으로 수신했다면, 고객님의 서버는 반드시 HTTP 상태 코드 200 (성공)과 함께, 응답 Body에 {“msgKey”:”전달 받은 실제 msgKey 값”} 형식의 JSON 데이터를 포함하여 응답해야 합니다.
✅ 재전송 정책 및 차단 조건
만약 이 규격에 맞지 않거나 응답이 지연(Timeout 5초)되면, 시스템에서는 데이터 전달 실패로 간주하고 최대 3회까지 재전송을 시도합니다. 하지만 1일 기준 수신 실패 횟수가 1,000회를 초과하면, 해당 계정의 웹훅 리포트 전달이 일시적으로 차단될 수 있으니, 수신 서버의 안정성과 정확한 응답 처리가 매우 중요합니다.
Tip: 웹훅 요청을 받자마자 일단 빠르게 성공 응답(200, {“msgKey”:”…”})을 먼저 보내고, 실제 데이터 처리는 비동기 방식으로 백그라운드에서 수행하는 아키텍처를 권장합니다. 이렇게 하면 타임아웃 문제없이 안정적으로 웹훅 데이터를 수신하고 처리할 수 있습니다.
📊 웹훅 데이터 파헤치기: 어떤 정보를 어떻게 활용할까?
Q3. 웹훅으로 받는 데이터 중 어떤 값을 필수로 로깅하고 모니터링해야 할까요?
A3. 안정적인 메시징 시스템 운영과 효과적인 서비스 품질 관리를 위해, 웹훅으로 수신하는 데이터 중 다음 파라미터들은 특히 주의 깊게 확인하고 활용하는 것이 좋습니다. (전체 파라미터는 비즈고 개발자 문서 – Webhook 참고)
| 파라미터 | 타입 | 설명 |
|---|---|---|
| msgKey | String | 메시지 발송 요청 시 생성되었던 고유 메시지 식별키 |
| reportCode | String | 메시지의 최종 전송 상태를 나타내는 결과 코드 (성공: 10000) |
| reportType | String | 수신한 리포트의 종류 (예: 0: 최종 결과) |
| msgType | String | 발송된 메시지의 실제 타입 (예: SM, LM, AT, FT 등) |
| serviceType | String | 발송 시 사용된 서비스의 타입 (예: SMS, ALIMTALK 등) |
| reportTime | String | 리포트가 생성된 일시 (ISO 8601 형식) |
주요 파라미터
실시간 모니터링 시에는 reportCode 유형별 건수, 특정 reportCode 발생 빈도 등을 주시하면 시스템의 이상 징후를 빠르게 감지하고 대응하는 데 큰 도움이 됩니다.
🚨 API 최종 결과 코드 분석 및 대응 전략
Q4. API 최종 결과 코드(Report Code)가 너무 많은데, 주요 실패 코드와 대응 방안을 알려주세요!
A4. 비즈고는 상세한 결과 코드를 제공하여 다양한 상황에 대처할 수 있도록 지원합니다. 모든 코드는 비즈고 API 응답 코드 문서 – Report Code에서 확인 가능하며, 여기서는 개발 시 특히 유의해야 할 주요 리포트 코드 대역과 기본적인 대응 방향을 안내해 드립니다.
먼저, 주요 Report Code 대역은 메시지 종류나 결과의 성격에 따라 다음과 같이 구분될 수 있습니다. 이 대역을 통해 어떤 종류의 메시지에서 결과가 발생했는지 대략적으로 파악하는 데 도움이 됩니다.
| Report Code | 설명 |
|---|---|
| 10000 | 성공 : 단말기 메시지 정상 도착 |
| 20000번대 | SMS/MMS/국제메시지 리포트 |
| 30000번대 | RCS GW 자체 리포트 |
| 40000번대 | RCS MAPP 리포트 |
| 50000번대 | RCS 이통사 리포트 |
| 60000번대 | 카카오 비즈메시지 리포트 |
| 70000번대 | 네이버톡톡(미출시) |
| 90000번대 | OMNI API 자체 에러 리포트 |
주요 Report Code 대역
위 표에서 보시는 것처럼, reportCode는 메시지 종류별로 결과 코드 대역이 나뉘어 있습니다. 예를 들어 SMS/MMS의 최종 결과는 주로 20000번대에서, 카카오 비즈메시지 결과는 60000번대에서 확인하실 수 있죠.
이제, 이처럼 다양한 결과 코드 중에서 개발자분들이 실제 운영 시 자주 마주치거나 중요하게 처리해야 하는 대표적인 Report Code 몇 가지 예시와 그에 따른 권장 대응 방향을 자세히 살펴보겠습니다.
| Report Code | 의미 | 권장 대응 방향 |
|---|---|---|
| 10000 | 성공 (단말기 메시지 정상 도착) | 성공으로 기록하고 내부 DB를 업데이트합니다. |
| 22003 32003 |
단말기 전원 꺼짐 | 일시적인 전달 불가 상황일 수 있으므로, 일정 시간 후 재시도를 고려해볼 수 있습니다 (예: 2~3회). 반복적인 경우 해당 수신번호의 유효성을 점검하거나 고객에게 다른 연락 수단을 요청할 수 있습니다. |
| 22004 32004 |
단말기 메시지 버퍼 풀 | |
| 23012 33012 |
스팸 | 메시지 내용(특수문자, 광고성 문구 등)에 스팸성 문구는 없는지 등 스팸 규정을 검토하여 수정 후 재발송을 시도해야 합니다. |
| 63016 63027 63028 63030 |
메시지 내용이 템플릿과 일치하지 않음 | 발송한 메시지 내용과 카카오에 등록/승인된 비즈메시지 템플릿의 내용(변수 포함)이 정확히 일치하는지 확인하고 수정해야 합니다. (빈칸, 필요없는 부호 등 체크 필요) |
대표 Report Code 예시 및 권장 대응 방향
✨ 비즈고 웹훅과 함께라면, 메시지 전송 현황 관리가 더욱 스마트해집니다!
고객에게 보내는 메시지, 성공적으로 전달되었는지 실시간으로 파악하는 것은 안정적인 서비스 운영의 핵심입니다. 다양한 변수로 인해 발생할 수 있는 전송 결과들을 빠르고 정확하게 확인하고 대응할 수 있다면, 고객 경험을 개선하고 서비스 신뢰도를 한층 높일 수 있겠죠.
비즈고의 실시간 웹훅 리포팅 기능을 활용하면, 더 이상 전송 결과를 확인하기 위해 주기적으로 서버를 호출하거나, 오류 발생 사실을 뒤늦게 알아차리는 불편함을 겪지 않아도 됩니다. 또한, 비즈고는 상세한 개발자 문서 (API 가이드북 및 결과 코드 문서)를 제공하고 있습니다.
이제 비즈고와 함께 스마트한 결과 확인 및 대응 시스템을 구축하고, 고객에게 항상 안정적이고 신뢰도 높은 메시징 서비스를 제공하세요!
