이 문서는 카카오 로그인 웹훅 기능을 안내합니다.

웹훅(Webhook)은 카카오 로그인 사용자의 계정 상태에 변경 사항이 생겼을 때, 카카오디벨로퍼스에 설정된 웹훅 URL로 HTTP 요청을 보내 서비스에게 공유하는 기능입니다.

카카오 로그인 관련 웹훅은 OpenID 재단에서 개발 및 제공하는 Shared Signals and Events Framework(SSF) 규격을 바탕으로 설계됐으며, 일부 이벤트는 카카오에서 직접 정의하여 제공합니다.

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

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

연결 해제 웹훅은 사용자가 서비스 외부에서 앱과 연결을 끊은 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다.

웹훅을 수신한 서비스는 내부 정책에 따라 사용자 정보를 처리한 뒤, HTTP 상태 코드 200 OK로 3초 내에 응답해야 합니다. 사용자 정보가 없거나 오류 발생 시에도 200 OK으로 응답해야 합니다.

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

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

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

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

아래는 사용자가 서비스 외부에서 연결을 끊을 때 카카오가 서비스에게 보내는 웹훅 요청 예시입니다.

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

계정 상태 변경 웹훅은 사용자의 계정 상태가 바뀔 때마다 이벤트 정보를 지정한 웹훅 URL로 전송하는 기능입니다.

구현 방법은 구현 절차를 참고합니다.

지원하는 카테고리별 이벤트는 아래와 같습니다. [이벤트 타입] 열의 이름을 선택하면 해당 이벤트의 상세 정보에서 이벤트 페이로드를 확인할 수 있습니다.

CAEP, RISC 카테고리의 변경 이벤트는 민감 정보를 포함합니다. 따라서 [카카오계정 상태 변경 내역] 동의항목 설정 및 사용자 동의가 필요합니다.

필요 시 아래 절차를 수행합니다.

1. 데브톡으로 [카카오계정 상태 변경 내역] 동의항목의 동의 단계 설정 권한 요청
   • 해당 권한은 적합성 검토 후 제공하므로, 요청 시 구체적인 사용 시나리오 포함 필요
2. 권한 부여 후, 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 [카카오계정 상태 변경 내역]을 [필수 동의] 또는 [선택 동의] 동의 단계로 설정 (참고: 설정하기)

• 이벤트 발생 시점: 카카오 로그인으로 발급한 사용자의 모든 토큰 만료
• 필수 조치 사항: 현재 열려 있는 서비스 세션을 종료하여 사용자 계정 보호
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked

• 이벤트 발생 시점: 사용자가 앱과 연결
• 권장 조치 사항: [로그인 시 앱 자동 연결]을 [사용 안 함]으로 설정한 앱인 경우, 회원 가입 완료 처리 외 서비스에서 필요한 조치 수행
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-linked

• 이벤트 발생 시점: 사용자가 앱과 연결 해제
• 권장 조치 사항: 사용자 회원 정보의 카카오 로그인 연동을 해제하거나, 카카오 로그인으로만 이용 가능한 경우에는 회원 탈퇴 처리(참고: 연결 해제 웹훅)
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-unlinked

• 이벤트 발생 시점: 사용자가 카카오 로그인을 통해 동의항목에 동의
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-scope-consent

• 이벤트 발생 시점: 사용자가 동의한 동의항목에 대해 동의 철회
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-scope-withdraw

• 이벤트 발생 시점: 비즈니스 인증을 통해비즈니스 토큰 신규 발급
• 권장 조치 사항: 발급된 비즈니스 토큰 정보 저장 및 관리
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/token-issued

아래 표와 페이로드 예시 참조.

아래는 비즈니스 토큰 관련 이벤트의 SET 페이로드 예시입니다.

{
  "events": {
    "https://schemas.openid.net/secevent/oauth/event-type/token-issued": {
      "subject": {
        "subject_type": "oauth_token",
        "token_type": "access_token",
        "token_identifier_alg": "hash_sha256",
        "token": "base64url(sha256(${TOKEN_VALUE}))"
      },
      "token_subject": {
        "subject_type": "iss-sub",
        "iss": "https://kauth.kakao.com/",
        "sub": "${TOKEN_USER_ID}"
      },
      "token_id": "${TOKEN_ID}",
      "token_class": "business"
    }
  }
}

• 이벤트 발생 시점: 비즈니스 인증을 통해 발급된 비즈니스 토큰 발급 철회
• 필수 조치 사항: 해당 비즈니스 토큰으로의 API 호출 중단
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/token-revoked

아래 표와 페이로드 예시 참조.

• 이벤트 발생 시점: 사용자에게 발급된 모든 비즈니스 토큰을 발급 철회
• 필수 조치 사항: 해당 사용자의 모든 비즈니스 토큰 사용 중단
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked

아래 표와 페이로드 예시 참조.

RISC 카테고리 이벤트는 동의항목 설정 및 사용자 동의가 필요합니다.

• 이벤트 발생 시점: 계정 비밀번호 변경
• 권장 조치 사항: 서비스에서 의심스러운 활동이 있는지 확인하여 필요한 후속 조치 결정
• 스키마: https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required

• 이벤트 발생 시점: 계정 비활성화
  카카오계정 보호 조치, 잠금 처리, 이용 제재 시
• 필수 조치 사항: 계정이 비활성화된 이유가 hijacking인 경우 현재 열려 있는 세션을 종료하여 사용자 계정 보호, 계정이 비활성화된 이유가 bulk-account인 경우 서비스에서 사용자의 활동을 분석하고 필요한 후속 조치 결정
• 스키마: https://schemas.openid.net/secevent/risc/event-type/account-disabled

• 이벤트 발생 시점: 계정 활성화
  카카오계정 휴면 또는 도용 상태에서 복구될 때 발생
• 권장 조치 사항: 사용자의 카카오 로그인 및 카카오계정 이메일 주소로 계정 복구 기능을 다시 활성화
• 스키마: https://schemas.openid.net/secevent/risc/event-type/account-enabled

• 이벤트 발생 시점: 계정 탈퇴
• 권장 조치 사항: 사용자 계정 삭제 또는 다른 로그인 방법 제공
• 스키마: https://schemas.openid.net/secevent/risc/event-type/account-purged

• 이벤트 발생 시점: 계정 자격증명 손상
  카카오계정 자격증명이 탈취 의심되는 경우(예: 계정 탈취가 의심되는 새로운 환경에서 로그인 성공)
• 권장 조치 사항: 서비스에서 의심스러운 활동이 있는지 확인하여 필요한 후속 조치 결정
• 스키마: https://schemas.openid.net/secevent/risc/event-type/credential-compromise

• 이벤트 발생 시점: 계정 식별자 변경 시, 사용자의 이메일 또는 전화번호가 변경된 경우
• 권장 조치 사항: 기존 사용자의 전화번호 또는 이메일을 파기하고, 변경된 전화번호나 이메일로 업데이트
• 스키마: https://schemas.openid.net/secevent/risc/event-type/identifier-changed

• 이벤트 발생 시점: 기존 계정 식별자 사용 불가, 카카오계정의 이메일 또는 전화번호가 다른 사용자에게 사용돼 이메일 인증 만료(Expired), 유예(Suspended) 상태가 된 경우
• 권장 조치 사항: 사용자 계정의 이메일 및 전화번호를 더 이상 사용하지 않도록 처리하고, 서비스에서 직접 새로운 이메일 및 전화번호 수집
• 스키마: https://schemas.openid.net/secevent/risc/event-type/identifier-recycled

• 이벤트 발생 시점: 계정의 모든 세션 만료
  비밀번호 변경 후 기존 기기 로그아웃 처리 시
• 필수 조치 사항: 현재 열려 있는 세션을 종료하여 사용자 계정 보호
• 스키마: https://schemas.openid.net/secevent/risc/event-type/sessions-revoked

CAEP 카테고리 이벤트는 동의항목 설정 및 사용자 동의가 필요합니다.

• 이벤트 발생 시점: 인증 보안 수준 변경
  2차 인증 설정 등 보안 수준 변경 시 발생
• 권장 조치 사항: 현재 사용자가 서비스 이용에 필요한 인증 보안 수준을 충족하는지 확인 후, 필요에 따라 재인증 등 조치를 거쳐 서비스 제공
• 스키마: https://schemas.openid.net/secevent/caep/event-type/assurance-level-change

• 이벤트 발생 시점: 계정 비밀번호 변경
  비밀번호 재설정 또는 카카오 인증서 재발급 시 발생
• 스키마: https://schemas.openid.net/secevent/caep/event-type/credential-change

• 이벤트 발생 시점: 사용자의 카카오계정 정보 변경
  단, 사용자가 제공 동의한 정보 변경 시에만 알림
• 권장 조치 사항: 사용자 정보 조회 API를 호출하여 변경된 정보로 업데이트
• 스키마: https://schemas.kakao.com/platevent/kakao/event-type/user-profile-changed

서비스는 카카오계정의 변경 이벤트 정보가 담긴 보안 이벤트 토큰(Security Event Token, SET)을 POST 메서드로 전달받습니다.

아래는 웹훅 URL로 전달되는 요청 예시입니다. 웹훅 요청의 헤더(Header) Content-Type은 application/secevent+jwt, 본문은 변경 이벤트 정보가 담긴 SET 값입니다. SET은 JWT(JSON Web Token) 형식의 토큰으로, 아래 세 가지 영역으로 구성돼 있습니다.

POST /kakao/events HTTP/1.1
Host: callback.example.com
Content-Type: application/secevent+jwt
Accept: application/json

eyJraWQiOiI2NjVhYmVlYzExOGRkZmMyZDNiZjNlMmFkYWU3OT...

SET은 세 영역의 값을 Base64 인코딩(Encoding) 한 후 온점(.)으로 이어 붙인 하나의 문자열로 생성됩니다. 따라서 온점을 기준으로 각 영역을 분리하고, Base64 디코딩(Decoding)하여 내용을 확인할 수 있습니다. 서비스는 SET 검증 후 페이로드 내용을 확인하여 필요한 사용자 계정 보호 조치를 수행할 수 있습니다. 아래는 디코딩된 SET 헤더와 페이로드 예제입니다.

{
  "kid": "665abeec118ddfc2d3bf3e2adae799",
  "typ": "secevent+jwt",
  "alg": "RS256"
}

아래는 헤더, 페이로드 영역에 포함되는 필드의 상세 정보입니다.

서비스는 변경 이벤트 정보에 따른 사용자 계정 보호 조치를 수행하기 전 반드시 SET 내용을 확인하고 검증해야 합니다. 아래 순서로 SET 내용을 확인하고 검증할 수 있습니다.

1. 온점(.)을 기준으로 헤더, 페이로드, 서명을 분리
2. 페이로드를 Base64 방식으로 디코딩
3. 페이로드의 iss 값이 https://kauth.kakao.com와 일치하는지 확인
4. 페이로드의 aud 값이 서비스 앱의 REST API 키와 일치하는지 확인
5. 서명 검증

서명 검증은 아래 순서로 수행합니다.

1. 헤더를 Base64 방식으로 디코딩
2. OIDC: 공개키 목록 조회로 카카오 인증 서버가 서명 시 사용하는 공개키 목록 조회
3. 공개키 목록에서 헤더의 kid에 해당하는 공개키 값 확인
   • 공개키는 일정 기간 캐싱(Caching)하여 사용할 것을 권장하며, 지나치게 빈번한 요청 시 요청이 차단될 수 있으므로 유의
4. JWT 서명 검증을 지원하는 라이브러리를 사용해 공개키로 서명 검증
   • 참고: OpenID Foundation, jwt.io
   • 라이브러리를 사용하지 않고 직접 서명 검증 구현 시, RFC7515 규격에 따라 서명 검증 가능

SET 수신 서버가 웹훅 수신 후 SET 검증에 성공한 경우, 본문 없이 HTTP 상태 코드 202 Accepted로 3초 내에 응답해야 합니다. 아래 예제를 참고합니다.

HTTP/1.1 202 Accepted

SET 수신 서버가 웹훅 수신 후 SET 검증에 실패한 경우, 아래 형식으로 3초 내에 응답해야 합니다.

• HTTP 상태 코드: 400 Bad Request
• 헤더의 Content-Type: application/json
• 본문: JSON 형식으로 RFC8935 규격에 따라 에러 코드(err)와 이유(description) 포함

아래 예제를 함께 참고합니다.

// HTTP/1.1 400 Bad Request
// Content-Type: application/json
{
  "err": "invalid_key",
  "description": "Key ID 12345 has been revoked."
}

계정 상태 변경 웹훅 시스템의 규격을 확인합니다.

curl -X GET https://kauth.kakao.com/.well-known/ssf-configuration

// HTTP/1.1 200
{
  "issuer": "https://kauth.kakao.com",
  "jwks_uri": "https://kauth.kakao.com/.well-known/jwks.json",
  "delivery_methods_supported": "http://schemas.openid.net/secevent/risc/delivery-method/push"
}

계정 상태 변경 웹훅을 테스트할 수 있습니다. [도구] > [웹훅 테스트]에서 테스트 기능을 확인할 수 있습니다. 자세한 내용은 계정 상태 변경 웹훅 테스트를 참고합니다.