이 문서는 카카오톡 공유 관련 웹훅 정보를 안내합니다.
이 문서는 서비스에서 카카오 API를 호출하는 방식이 아닌, 카카오가 서비스의 엔드포인트로 전송하는 웹훅 요청에 대한 명세를 설명합니다.
웹훅 기능의 전체 흐름과 구현 방식은 구현 절차에서 먼저 확인할 수 있습니다.
SDK에서 카카오톡 공유 API 호출 시, serverCallbackArgs
로 사용자 정의 파라미터를 지정해야 카카오톡 공유 웹훅을 수신할 수 있습니다. 자세한 내용은 플랫폼별 개발 가이드를 참고합니다.
메서드 | URL | 필수 응답 규격 | 인증 방식 |
---|---|---|---|
GET/POST |
앱 관리 페이지의 [앱] > [웹훅] > [카카오톡 공유 웹훅]에 등록한 웹훅 URL | HTTP 상태 코드 2XX (3초 내) |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 카카오톡 공유 웹훅 사용자 정의 파라미터 설정 |
- | - |
카카오톡 공유 웹훅은 사용자가 선택한 친구 또는 채팅방으로 카카오톡 공유 메시지가 성공적으로 전달된 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다. 웹훅을 수신한 서비스는 HTTP 상태 코드 2XX
로 3초 내에 응답해야 합니다.
카카오톡 공유 API는 카카오톡 메시지 API와의 구조적 차이로 인해 웹훅으로만 발송 결과를 확인할 수 있습니다. 두 API의 차이점은 기능 소개를 참고합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
Authorization | String |
Authorization: KakaoAK ${APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
X-Kakao-Resource-ID | String |
카카오톡 공유 웹훅별 고유 ID (예: Rvy1c2dkzBAZ5hGD3rqYbxvr ) |
O |
User-Agent | String |
카카오에서 보낸 요청임을 알리기 위한 문자열KakaoOpenAPI/1.0 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
CHAT_TYPE | String |
카카오톡 공유 메시지가 전달된 채팅방의 타입, 아래 중 하나 MemoChat : 나와의 채팅방DirectChat : 다른 사용자와의 1:1 채팅방MultiChat : 다른 사용자들과의 그룹 채팅방OpenDirectChat : 1:1 오픈채팅방OpenMultiChat : 그룹 오픈채팅방 |
O |
HASH_CHAT_ID | String |
카카오톡 공유 메시지를 수신한 채팅방의 참고용 ID 서비스별로 유일(Unique)한 해시(Hash) 값으로, 같은 채팅방이라도 서비스마다 다른 값 제공 참고: 얼마나 많은 채팅방으로 카카오톡 공유가 발송되었는지 확인 가능 |
O |
${CUSTOM_KEY}":"${CUSTOM_VALUE} |
JSON |
SDK에서 카카오톡 공유 API 호출 시 서비스에서 직접 정의한 사용자 정의 파라미터serverCallbackArgs 파라미터 키와 값을 JSON 형식으로 입력해야 함(예: {"user_id":"abcd","product_id":1234} ) |
O |
TEMPLATE_ID | Long |
메시지 템플릿으로 카카오톡 공유 메시지를 보낸 경우 사용한 메시지 템플릿의 ID, 메시지 템플릿 ID를 사용해 요청하지 않은 경우 전달되지 않음 | X |
웹훅 요청을 받은 후 3초 내에 HTTP 상태 코드 2XX
로 응답해야 합니다.
아래는 카카오톡 공유 메시지가 사용자에게 성공적으로 전달됐을 때 카카오가 서비스에게 보내는 웹훅 요청 예시입니다.
curl -v -G GET "${KAKAOLINK_CALLBACK_URL}?CHAT_TYPE=MemoChat&HASH_CHAT_ID=${HASH_CHAT_ID}&TEMPLATE_ID=10000&custom_parameter_key=custom_parameter_value" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \
-H "User-Agent: KakaoOpenAPI/1.0"
curl -v -X POST "${KAKAOLINK_CALLBACK_URL}" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \
-H "User-Agent: KakaoOpenAPI/1.0" \
-H "Content-Type: application/json" \
-d '{
"CHAT_TYPE":"MemoChat",
"HASH_CHAT_ID":"${HASH_CHAT_ID}",
"TEMPLATE_ID":10000,
"custom_parameter_key":"custom_parameter_value"
}'