웹훅

이 문서는 카카오톡 채널 관련 웹훅 정보를 안내합니다.

시작하기 전에

이 문서는 서비스에서 카카오 API를 호출하는 방식이 아닌, 카카오가 서비스의 엔드포인트로 전송하는 웹훅 요청에 대한 명세를 설명합니다.

웹훅 기능의 전체 흐름과 구현 방식은 구현 절차에서 먼저 확인할 수 있습니다.

카카오톡 채널 웹훅은 앱 관리 페이지의 [앱] > [카카오톡 채널] > [연결된 카카오톡 채널]에 등록된 카카오톡 채널을 기준으로 발송됩니다. 따라서 카카오톡 공유 웹훅을 사용하려면 카카오톡 채널을 비즈니스 채널로 전환 후 앱과 연결해야 합니다. 연결 조건은 연결 가능 카카오톡 채널을 참고합니다.

카카오톡 채널 웹훅

기본 정보

메서드	URL	필수 응답 규격	인증 방식
POST	앱 관리 페이지의 [앱] > [웹훅] > [카카오톡 채널 웹훅]에 등록한 웹훅 URL	HTTP 상태 코드 2XX (3초 내)	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
-	카카오 로그인 활성화 앱에 카카오톡 채널 연결 카카오톡 채널 웹훅	-	-

카카오톡 채널 웹훅은 사용자가 앱에 연결된 카카오톡 채널을 추가하거나 차단한 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다. 웹훅을 수신한 서비스는 HTTP 상태 코드 2XX로 3초 내에 응답해야 합니다.

웹훅 기능을 구현하는 방법은 구현 절차를 참고합니다.

요청

헤더

이름	타입	설명	필수
Authorization	String	유효한 요청인지 판단할 수 있도록 전달하는 앱 어드민 키 Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}	O
X-Kakao-Resource-ID	String	카카오톡 채널 웹훅별 고유 ID (예: Rvy1c2dkzBAZ5hGD3rqYbxvr)	O
User-Agent	String	카카오에서 보낸 요청임을 알리기 위한 문자열 KakaoOpenAPI/1.0	O

본문

이름	타입	설명	필수
event	String	사용자와 카카오톡 채널의 관계 변경 사항, 추가(added) 또는 차단(blocked)	O
id	String	카카오톡 채널 추가 또는 차단한 사용자 식별자	O
id_type	String	식별자 타입, app_user_id 또는 open_id app_user_id: 카카오 로그인 동의항목 중 [카카오톡 채널 추가 상태 및 내역]에 동의한 사용자 open_id: [카카오톡 채널 추가 상태 및 내역]에 동의하지 않은 사용자	O
channel_public_id	String	사용자와 카카오톡 채널의 관계가 변경된 카카오톡 채널의 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법	O
channel_uuid	String	카카오톡 채널의 검색용 ID	O
updated_at	Datetime	카카오톡 채널 관계가 변경된 시간, UTC* (RFC3339 internet date/time format)	O

* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고

* plus_friend_public_id: Deprecated, 카카오톡 채널의 프로필 ID(String), channel_public_id를 사용하도록 변경, 공지 참고

* plus_friend_uuid: Deprecated, 카카오톡 채널의 검색용 ID(String), channel_uuid를 사용하도록 변경, 공지 참고

* timestamp: Deprecated, 카카오톡 채널 관계가 변경된 시간(Long, 단위: ms), updated_at을 사용하도록 변경

응답

웹훅 요청을 받은 후 3초 내에 HTTP 상태 코드 2XX로 응답해야 합니다.

예제

아래는 카카오톡 채널이 추가되거나 차단됐을 때 카카오가 서비스에게 보내는 웹훅 요청 예시입니다.

요청

curl -v -X POST "${KAKAOTALK_CHANNEL_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 '{
            "event":"added",
            "id":"1111",
            "id_type":"app_user_id",
            "channel_public_id":"_FLX", // 추가
            "channel_uuid":"@ad",   // 추가
            "updated_at":"2019-11-21T10:14:07Z"
        }'