Message Webhook

문자 메시지(SMS/LMS/MMS) 관련 이벤트가 발생할 때 전송되는 Message Webhook의 파라미터를 안내합니다.

Message Webhook은 문자 메시지(SMS/LMS/MMS) 관련 이벤트가 발생하면 설정된 URL로 알림을 전송합니다. 계정 레벨에서 REST API로 등록합니다.

등록

POST /v1/accounts/{accountId}/webhooks

Body:
{
  "url": "https://my-app.com/message-webhook",
  "events": ["message.sent", "message.failed", "message.received"]
}

배송 로그 조회

SDK로 웹훅 배송 로그를 확인할 수 있습니다.

page = client.webhook_logs.list("cmob6...", page=0, page_size=20)
for log in page.data:
    print(log)

이벤트 종류

파라미터	타입	필수	설명
message.sent	event	선택	메시지 발송 완료
message.failed	event	선택	메시지 발송 실패
message.received	event	선택	메시지 수신 (인바운드)

요청 파라미터

모든 요청은 Content-Type: application/x-www-form-urlencoded POST 입니다. 이벤트마다 전달되는 파라미터가 다르니 아래 세 표를 참고하세요.

message.sent

KCT 로부터 최종 발송 성공 리포트를 수신한 직후 전송됩니다 (아웃바운드 전용).

파라미터	타입	필수	설명
MessageId	string	필수	메시지 고유 ID
AccountId	string	필수	계정 ID
From	string	필수	발신 번호
To	string	필수	수신 번호
Direction	string	필수	고정값 outbound
Type	string	필수	메시지 유형 (sms, lms, mms)
Status	string	필수	고정값 sent
Timestamp	string	필수	이벤트 발생 시각 (ISO 8601)

MessageId=MGabc123&AccountId=ACxxx&From=%2B821011112222&To=%2B821033334444
&Direction=outbound&Type=sms&Status=sent
&Timestamp=2026-04-23T09:12:44.123Z

message.failed

발송 요청이 KCT 블랙리스트/데이터 오류 또는 실패 리포트로 종료된 경우 전송됩니다 (아웃바운드 전용).

파라미터	타입	필수	설명
MessageId	string	필수	메시지 고유 ID
AccountId	string	필수	계정 ID
From	string	필수	발신 번호
To	string	필수	수신 번호
Direction	string	필수	고정값 outbound
Type	string	필수	메시지 유형 (sms, lms, mms)
Status	string	필수	고정값 failed
Timestamp	string	필수	이벤트 발생 시각 (ISO 8601)

MessageId=MGabc123&AccountId=ACxxx&From=%2B821011112222&To=%2B821033334444
&Direction=outbound&Type=sms&Status=failed
&Timestamp=2026-04-23T09:12:44.123Z

message.received

인바운드 메시지가 도착해 저장(및 MMS 첨부 업로드)이 완료된 직후 전송됩니다.

파라미터	타입	필수	설명
MessageId	string	필수	메시지 고유 ID
AccountId	string	필수	계정 ID
From	string	필수	발신 번호
To	string	필수	수신 번호
Direction	string	필수	고정값 inbound
Type	string	필수	메시지 유형 (sms, lms, mms)
Subject	string	필수	메시지 제목. SMS 또는 제목이 없는 경우 빈 문자열
Body	string	필수	메시지 본문
Status	string	필수	고정값 received
NumMedia	string	필수	첨부 미디어 수. MMS 가 아니면 0
MediaUrl0	string	선택	첨부 미디어 URL (MMS 에서 NumMedia 만큼 MediaUrl0, MediaUrl1 … 형태로 포함)
Timestamp	string	필수	이벤트 발생 시각 (ISO 8601)

MessageId=MGabc123&AccountId=ACxxx&From=%2B821011112222&To=%2B821033334444
&Direction=inbound&Type=mms&Subject=%EC%95%88%EB%82%B4&Body=%EC%98%A4%EB%8A%98+%EC%98%88%EC%95%BD
&Status=received&NumMedia=1&MediaUrl0=https%3A%2F%2Fstorage.googleapis.com%2F...
&Timestamp=2026-04-23T09:12:44.123Z

예제

from flask import Flask, request

app = Flask(__name__)

@app.route("/message-webhook", methods=["POST"])
def message_webhook():
    status = request.form.get("Status")
    message_id = request.form.get("MessageId")

    if status == "received":
        body = request.form.get("Body", "")
        print(f"수신 메시지 [{message_id}]: {body}")
    elif status == "failed":
        to = request.form.get("To")
        print(f"발송 실패 [{message_id}] → {to}")
    elif status == "sent":
        print(f"발송 완료 [{message_id}]")

    return "", 204

Message Webhook 요청에도 X-Signature 헤더가 포함됩니다. 서명 검증 가이드를 참고하여 요청의 무결성을 확인하세요.

Message Webhook

On this page