이 문서는 카카오 또는 공동체 서비스용 카카오 로그인 관련 웹훅 기능을 안내합니다.

이용 정책에서 웹훅 사용 시 주의 사항을 확인해야 합니다.

사용자의 연결 해제 발생 시, 사유별 카카오에서 서비스로 요청하는 웹훅과 API 목록입니다.

연결 해제 웹훅은 사용자가 서비스 외부에서 앱과 연결을 끊은 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다. 웹훅을 수신한 서비스는 내부 정책에 따라 사용자 정보를 처리한 뒤, HTTP 상태 코드 200 OK로 3초 내에 응답해야 합니다.

서비스 외부에서 연결 해제를 요청한 사용자에게는 더 이상 해당 서비스를 사용할 수 없다는 문구가 표시됩니다. 연결 해제 웹훅은 사용자에 대한 연결 해제 처리를 완료한 후 발송합니다.

웹훅은 헤더에 대표 어드민 키를, 본문에 앱 ID(app_id), 회원번호(user_id), 연결 해제 요청 경로(referrer_type)를 각각 포함합니다.

연결 해제 웹훅은 웹훅 URL과 메서드를 지정해야 사용할 수 있으며, 리다이렉트는 지원하지 않습니다. 설정 방법은 연결 해제 웹훅을 참고합니다.

아래 상황이 발생한 경우 연결 해제 웹훅을 발송합니다. 서비스가 연결 해제 API를 호출해 앱과 사용자의 연결을 끊은 경우에는 연결 해제 웹훅을 발송하지 않습니다.

• 가입 미완료 사용자 연결 해제 처리
• 사용자가 카카오계정 관리 페이지나 카카오톡의 연결된 서비스 관리 메뉴에서 앱과의 연결을 끊은 경우
• 사용자의 카카오계정 탈퇴
• CS로 인한 연결 해제 처리

서비스는 웹훅 수신 시 필요한 작업 수행 후 정해진 규격으로 응답해야 합니다. 아래 과정을 참고합니다.

1. 수신한 웹훅의 유효성을 포함된 대표 어드민 키와 app_id로 검증합니다.
2. 수신한 웹훅이 유효한 경우, user_id에 해당하는 사용자 정보를 개인정보 처리방침과 서비스 정책에 따라 탈퇴 처리, 삭제 또는 기타 방법으로 데이터베이스(DB)에 반영합니다.
3. 웹훅 수신 시점으로부터 3초 내에 HTTP 상태 코드 200 OK로 응답합니다.
   • HTTP 상태 코드로 응답 성공 여부를 판단하므로 본문(Body)은 필요하지 않습니다.
   • 사용자 정보 처리에 실패했거나, 사용자를 찾을 수 없는 경우에도 HTTP 상태 코드 200 OK로 응답해야 합니다. 이후 서비스 내부에서 필요한 작업을 수행합니다.

연결 해제 웹훅을 받으려면 사용자가 연결을 끊는 상황을 만들어야 합니다. 카카오계정 페이지 또는 카카오톡의 더보기 탭에 있는 카카오계정 관리 메뉴에서 연결 해제 기능을 제공합니다. 이 기능을 사용해 서비스 서버가 연결 해제 웹훅을 정상적으로 처리하는지 확인할 수 있습니다.

와치 센터 알림을 참고합니다.

• HTTP 상태 코드 200 OK (3초 내)

curl -v -G GET "${UNLINK_CALLBACK_URL}?app_id=${APP_ID}&user_id=${USER_ID}&referrer_type=UNLINK_FROM_APPS" \
  -H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}"

curl -v -X POST "${UNLINK_CALLBACK_URL}" \
  -H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \
  --data-urlencode "app_id=${APP_ID}" \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode "referrer_type=UNLINK_FROM_APPS"

HTTP/1.1 200 OK

연결 해제 웹훅 시 [연결 해제 불가능 사용자 포함] 설정을 한 경우, 연결 해제 불가 사유 API를 호출해야 합니다. 연결 해제 불가능한 경우가 있는 서비스에서 사용자가 연결 해제를 요청한 경우, 연결 해제 불가 사유 API를 호출해 연결을 끊을 수 없는 원인을 확인해 사용자에게 안내하는 데 사용됩니다.

연결 해제 불가 사유 API의 요청은 연결 해제 설정에 등록된 [연결 해제 불가 사유 API]의 URL로 사전에 정의된 파라미터들을 포함해 전달됩니다. 서비스에서는 아래 정보를 JSON 형식으로 응답의 deactivation 키 하위에 담아 제공해야 합니다. 응답의 HTTP Status는 성공 시 200으로 고정되어야 합니다.

• 카카오 API 플랫폼 서버에서 서비스 서버로 보내는 요청 규격입니다.

• 서비스 서버에서 카카오 API 플랫폼 서버로 반환해야 하는 응답 규격입니다.

• 아래 명시된 필드 이외의 다른 필드를 포함해도 무방하나, 명시된 필드 이외의 필드는 무시됩니다.
• 요청의 locale, mobile 파라미터를 참고해 사용자 환경에 맞는 정보를 응답에 제공해야 합니다.

curl -v -G "${등록된 연결 해제 불가 사유 API URL}" \
    -H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \
    -d "app_id=987000" \
    -d "account_id=1122" \
    -d "app_user_id=1376016924429759250" \
    -d "locale=ko" \
    -d "mobile=false"

{
  "deactivation": {
    "canDeactivate": true
  }
}

{
  "deactivation": {
    "canDeactivate": false,
    "title": "사용자 안내 제목입니다.",
    "message": "모든 정보 삭제 버튼을 누르면 나타나는 사용자 안내의 본문입니다."
  }
}

연결 해제 불가 사유 UI 예시

로그아웃 웹훅은 카카오 로그인 사용 서비스의 사용자가 서비스 외부에서 로그아웃을 요청 했거나, 계정 정보 수정 또는 제재 등으로 인한 로그아웃이 발생한 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다. 웹훅을 수신한 서비스는 HTTP 상태 코드 200 OK로 3초 내에 응답해야 합니다.

웹훅을 수신한 서비스는 로그아웃한 사용자의 서비스 세션을 만료시켜 푸시 알림 대상에서 제외하거나, 서비스 재이용 시 자연스러운 동선을 제공할 수 있습니다.

• 사용자는 웹훅 전송 성공 여부와 무관하게 로그아웃 처리됩니다.
• 연결 해제로 인한 로그아웃은 연결 해제 웹훅으로 처리해야 합니다.
• 로그아웃 웹훅은 모든 로그아웃 경로에 대한 웹훅 전송을 보장하지 않습니다. 서비스에서도 자체적으로 로그아웃으로 인한 토큰 만료 등 서비스 외부에서의 로그아웃에 대한 예외처리를 구현해야 합니다.

• HTTP 상태 코드 200 OK (3초 내)

curl -v -X GET "${LOGOUT_CALLBACK_URL}?app_id=${APP_ID}&user_id=${USER_ID}&referrer_type=UNLINK_FROM_APPS" \
  -H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}"

curl -v -X POST "${LOGOUT_CALLBACK_URL}" \
  -H "Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}" \
  -d "app_id=12345" \
  -d "app_user_id=1234567" \
  -d "referrer_type=LOGOUTALL_FROM_ACCOUNT"

HTTP/1.1 200 OK

계정 상태 변경 웹훅은 카카오 계정 상태가 변경됐을 때, 카카오 로그인을 사용하는 서비스에 변경 이벤트 정보를 전달하는 기능입니다. 계정 상태 변경 웹훅을 참고합니다.

• OAUTH
• CAEP: 공동체 앱은 권한 요청 필요
• RISC: 공동체 앱은 권한 요청 필요
• KAKAO: 인하우스 앱은 추가 이벤트 사용 가능

인하우스 앱은 아래 정책을 따릅니다.

• [카카오계정 상태 변경 내역] 동의항목을 설정하지 않아도 CAEP, RISC 이벤트를 사용할 수 있습니다.
• 앱 사용자가 정보 제공에 동의하지 않아도 변경 이벤트를 발송합니다.
• KAKAO 카테고리에서 아래 이벤트를 추가로 사용할 수 있습니다.

공동체 앱에서 CAEP, RISC 카테고리의 이벤트를 사용하려면 권한이 필요합니다.

1. [서비스] API플랫폼 아지트에서 [계정 상태 변경 웹훅 권한] 요청
2. 권한을 부여받은 후, 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 [카카오계정 상태 변경 내역]을 [필수 동의] 또는 [선택 동의] 동의 단계로 설정합니다.
   • 동의항목을 설정해도, 사용자가 [카카오계정 상태 변경 내역]에 동의한 경우에만 이벤트 정보가 전달됩니다.