사이드 메뉴
커뮤니케이션
API 제공
어드민 API
웹훅
이 문서는 문자 메시지 관련 웹훅 정보를 안내합니다.
문자 메시지 발송 API 요청의 결과를 발송 결과 웹훅에 설정된 웹훅 URL로 전달합니다. 발송 결과 웹훅은 이동통신사 또는 중계사로부터 문자 메시지 발송 결과가 전달된 시점에 발송됩니다. 문자 메시지 발송 API의 응답은 발송 결과와 수신 여부를 포함하지 않으나, 서비스는 발송 결과 웹훅을 받아 별도 API 요청 없이도 발송 결과와 수신 여부를 확인할 수 있습니다.
필요 시 요청 ID로 발송 결과 조회 API로 발송 결과를 별도 확인할 수 있습니다. 이동통신사 또는 중계사로부터의 문자 메시지 발송 결과 전달이 최대 3일까지 지연되는 경우가 있으므로, 발송 결과 웹훅이 지연되는 경우에는 API를 사용해 발송 상태를 확인할 수 있습니다.
요청 본문은 문자 메시지 한 건의 발송 결과를 포함합니다. 문자 메시지 발송에 실패한 경우, 결과 코드로 원인을 확인할 수 있습니다.
서비스는 발송 결과 웹훅을 수신하고 응답하는 기능을 직접 구현해야 합니다. 응답 규격, 허용 IP 등록 등 자세한 정보는 이용 정책을 참고합니다.
개별 문자 메시지가 아닌, 요청 ID(requestId)에 대한 발송 결과는 요청 ID로 발송 결과 조회 API로 확인할 수 있습니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| Authorization | String | Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}유효한 웹훅인지 판단할 수 있도록 전달하는 대표 어드민 키 | O |
| X-Kakao-Resource-ID | String | X-Kakao-Resource-ID: ${UNIQUE_ID}각 웹훅의 구분을 위한 고유 ID | O |
| User-Agent | String | User-Agent: KakaoOpenAPI/1.0카카오에서 보낸 웹훅임을 알리기 위한 문자열 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| message_id | String | 메시지 ID | O |
| status_code | String | 발송 요청의 상태 코드, 아래 중 하나
| O |
| status_msg | String | 발송 요청의 상태 설명 | O |
| result_code | String | 개별 문자 메시지 발송 결과에 대한 결과 코드 | O |
| result_msg | String | 개별 문자 메시지 발송 결과 설명 | O |
| report_date | String | 이동통신사 또는 중계사로부터 결과를 전달받은 일시, ISO8601 형식 (예: 2024-06-13T15:25:47+09:00) | X |
| message_count | Int | 과금 건수 국내 메시지는 항상 1국제 메시지는 분할 발송으로 인해 1 이상일 수 있음참고: 국제 메시지 발송 정책 | O |
curl -X POST "${WEBHOOK_URL}" \-H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \-H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \-H "User-Agent: KakaoOpenAPI/1.0" \-H "Content-Type: application/json" \-d '{"message_id": "${MESSAGE_ID}","status_code": "${STATUS_CODE}","status_msg": "${STATUS_MESSAGE}","result_code": "${RESULT_CODE}","result_msg": "${RESULT_MESSAGE}","report_date": "${REPORT_DATE}","message_count": ${MESSAGE_COUNT}}'
수신거부번호로 인입된 사용자의 문자 메시지 수신거부 요청을 앱 관리 페이지의 [문자 메시지] > [수신거부 웹훅]에 설정된 웹훅 URL로 전달합니다. 수신거부 웹훅은 사용자의 수신거부 요청이 성공적으로 처리된 후 전달됩니다. 서비스에서 수신거부 내역을 직접 관리하고자 할 경우, 수신거부 웹훅으로 편리하게 수신거부 내역을 업데이트할 수 있습니다.
요청 본문은 사용자가 수신거부를 요청할 때 사용한 수신거부번호, 사용자 전화번호를 포함합니다.
서비스는 수신거부 웹훅을 수신하고 응답하는 기능을 직접 구현해야 합니다. 응답 규격, 허용 IP 등록 등 자세한 정보는 이용 정책을 참고합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| Authorization | String | Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}유효한 웹훅인지 판단할 수 있도록 전달하는 대표 어드민 키 | O |
| X-Kakao-Resource-ID | String | X-Kakao-Resource-ID: ${UNIQUE_ID}각 웹훅의 구분을 위한 고유 ID | O |
| User-Agent | String | User-Agent: KakaoOpenAPI/1.0카카오에서 보낸 웹훅임을 알리기 위한 문자열 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| refusal_number | String | 수신거부번호(080) | O |
| request_number | String | 수신거부를 요청한 사용자 전화번호 | O |
curl -X POST "${WEBHOOK_URL}" \-H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \-H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \-H "User-Agent: KakaoOpenAPI/1.0" \-H "Content-Type: application/json" \-d '{"refusal_number": "${REFUSAL_NUMBER}","request_number": "${REQUEST_NUMBER}"}'
문자 메시지 수신 번호 할당 API로 할당받은 수신 번호에 사용자가 발송한 MO 메시지 내용을 웹훅 URL로 전달합니다. 문자 메시지 수신 웹훅은 이동통신사 또는 중계사로부터 MO 메시지 내용이 전달된 시점에 발송됩니다.
요청 본문은 수신 번호 정보, MO 메시지 내용과 정보를 포함합니다.
서비스는 메시지 수신 웹훅을 수신하고 처리하는 기능을 직접 구현해야 합니다. 응답 규격, 허용 IP 등록 등 자세한 정보는 이용 정책을 참고합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| Authorization | String | Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}유효한 웹훅인지 판단할 수 있도록 전달하는 대표 어드민 키 | O |
| X-Kakao-Resource-ID | String | X-Kakao-Resource-ID: ${UNIQUE_ID}각 웹훅의 구분을 위한 고유 ID | O |
| User-Agent | String | User-Agent: KakaoOpenAPI/1.0카카오에서 보낸 웹훅임을 알리기 위한 문자열 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 수신 번호 할당 요청 ID | O |
| sender | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드를 포함한 전화번호 | O |
| sender_country_code | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드 문자 메시지 수신 번호 할당 API 요청 시, sender_country_code를 사용한 경우, content 기준으로 매칭되어 요청 시 전달한 값과 다른 값이 전달 될 수 있음 (참고: 할당 단계 참고사항) | X |
| receiver | String | 할당된 MO 메시지 수신 번호(국가코드 포함) | O |
| receiver_country_code | String | 할당된 MO 메시지 수신 번호의 국가 코드 | O |
| content | String | 사용자가 발송한 MO 메시지 내용 | O |
| status | String | MO 메시지 수신 상태 | O |
| created_at | String | 수신 번호 할당 요청 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2025-10-13T15:25:47+09:00) | O |
| updated_at | String | 수신 상태 변경 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2025-10-13T15:25:47+09:00) | O |
curl -X POST "${WEBHOOK_URL}" \-H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \-H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \-H "User-Agent: KakaoOpenAPI/1.0" \-H "Content-Type: application/json" \-d '{"id": "8","sender": "821012345678","sender_country_code": "82","receiver": "447860099265","receiver_country_code": "44","content": "${MO_MESSAGE_CONTENT}","status": "UNMATCHED","created_at": "2025-10-20T11:56:20+09:00","updated_at": "2025-10-20T11:56:20+09:00"}'