게임플레이 파트너 가이드

테마 전환

동의 철회·연결 해제 웹훅 (디벨로퍼스 마이그레이션 가이드) ​

디벨로퍼스 마이그레이션 가이드

이 문서는 기존 약관 동의 철회 통지 API(파트너사 자체 구현 콜백)를 카카오디벨로퍼스 카카오 로그인 계정 상태 변경 웹훅으로 전환하기 위한 마이그레이션 전용 가이드입니다.
앞으로 제공될 디벨로퍼스 문서로 대체될 예정이며, 그때까지만 제공됩니다.
전환을 마친 뒤의 최신 규격은 계정 상태 변경 웹훅 연동을 참고하세요.

카카오가 파트너사 서버로 사용자의 카카오 로그인 계정 상태 변경 이벤트를 전달하는 웹훅입니다.
기존의 약관 동의 철회 통지 API(파트너사 자체 구현 콜백)는 디벨로퍼스에 등록하는 카카오 로그인 계정 상태 변경 웹훅 기반 연동으로 변경됩니다.

약관 철회로 인한 파트너사 앱 연결 해제는 카카오가 대신 처리합니다.
파트너사는 웹훅으로 전달되는 연결 해제 이벤트를 수신해 게임 이용 데이터 파기와 내부 상태 정리를 수행합니다.
약관 철회로 연결 해제된 사용자와 개별 앱에서 연결 해제된 사용자를 같은 웹훅에서 함께 받아 처리할 수 있습니다.

관련 가이드: 카카오싱크 설정: 앱·서비스 약관 설정, 카카오싱크 API: 연결 해제 요청, 심사 체크리스트: 철회 처리 자체 점검 항목

요청 본문(SET) 구조, 서명 검증, 성공/실패 응답 규격은 카카오 로그인 계정 상태 변경 웹훅 문서의 최신 내용을 따릅니다.
이 페이지는 게임플레이 파트너사의 처리 기준만 정의합니다.

변경 개요 ​

항목기존 방식변경 후
연동 방식카카오 게임플레이 서버가 파트너사 정의 API로 동의 철회 JSON 통지카카오 로그인 계정 상태 변경 웹훅으로 연결 해제 이벤트 수신
등록 위치카카오와 별도 협의카카오디벨로퍼스 [카카오 로그인] > [계정 상태 변경 웹훅]
요청 본문user_id · timestamp · reason JSONSET(Security Event Token) 형식의 JWT
약관 철회 시 앱 연결 해제파트너사가 직접 처리카카오가 처리
약관 철회 시 파트너사 처리연결 해제 + 데이터 파기데이터 파기 + 내부 상태 정리
개별 앱 연결 해제 처리별도 경로·정책 필요같은 OAUTH: User Unlinked 이벤트에서 reason으로 구분
요청/응답/검증 상세이 페이지에서 별도 정의디벨로퍼스 계정 상태 변경 웹훅 문서 기준

연동 대상 ​

파트너사는 카카오디벨로퍼스 앱 관리 페이지의 [카카오 로그인] > [계정 상태 변경 웹훅] 에 수신 웹훅 URL을 등록합니다.

파트너사가 처리해야 하는 핵심 이벤트는 OAUTH: User Unlinked입니다.

항목내용
이벤트 타입OAUTH: User Unlinked
Schemahttps://schemas.openid.net/secevent/oauth/event-type/user-unlinked
발생 시점사용자가 앱과 연결 해제된 경우
식별 정보SET payload의 사용자 회원번호 (sub, subject.sub)
구분 기준이벤트 상세 정보의 reason

인증 ​

SET 서명 검증 등 요청 인증·검증 규격은 디벨로퍼스 계정 상태 변경 웹훅 문서를 따릅니다.

요청 본문(SET) 형식과 Content-Type은 디벨로퍼스 계정 상태 변경 웹훅 문서 규격을 따릅니다.

reason별 처리 기준 ​

reason발생 상황파트너사 처리
REVOKE_ACCOUNT_SERVICE_TERMS통합서비스 약관 동의 철회로 앱 연결이 해제된 경우게임 데이터 파기 및 내부 연결 상태 정리
UNLINK_FROM_APPS사용자가 카카오계정 페이지에서 개별 앱 연결을 해제한 경우게임 데이터 파기 및 내부 연결 상태 정리
UNLINK_FROM_SERVICE서비스 탈퇴로 앱 연결이 해제된 경우서비스 탈퇴 정책에 따른 데이터 파기 및 내부 상태 정리
ACCOUNT_DELETE카카오계정 탈퇴게임 데이터 파기 및 내부 연결 상태 정리
FORCED_ACCOUNT_DELETE장기 휴면 또는 고객센터에 의한 카카오계정 강제 탈퇴게임 데이터 파기 및 내부 연결 상태 정리
UNLINK_FROM_ADMIN카카오 관리자에 의한 탈퇴 처리게임 데이터 파기 및 내부 연결 상태 정리
INCOMPLETE_SIGN_UP가입 미완료 사용자 연결 해제.
최초 로그인 후 24시간 이내에 사용자 정보 조회 API를 호출하지 않은 경우입니다		생성된 임시 데이터가 있다면 파기

핵심 변경점

기존에는 약관 철회 통지를 받은 뒤 파트너사가 직접 앱 연결 해제와 데이터 파기를 함께 처리했습니다.
웹훅 전환 후에는 REVOKE_ACCOUNT_SERVICE_TERMS 이벤트에서 앱 연결 해제는 카카오가 처리하고, 파트너사는 데이터 파기와 내부 상태 정리만 수행합니다.

파트너사 처리 요구사항 ​

  • 카카오디벨로퍼스에 계정 상태 변경 웹훅 URL을 등록합니다.
  • 디벨로퍼스 문서 기준으로 SET을 검증하고, 검증에 성공한 이벤트만 처리합니다.
  • OAUTH: User Unlinked 이벤트를 수신하면 reason에 따라 약관 철회와 개별 앱 연결 해제를 구분합니다.
  • reason = REVOKE_ACCOUNT_SERVICE_TERMS인 경우 앱 연결 해제는 카카오가 이미 처리하므로, 별도 연결 해제 API를 호출하지 않고 데이터 파기와 내부 상태 정리만 수행합니다.
  • reason = UNLINK_FROM_APPS 등 개별 앱 연결 해제 이벤트도 같은 웹훅에서 처리하고, 게임 데이터 파기 및 내부 연결 상태 정리를 수행합니다.
  • 철회·연결 해제를 수신한 사용자는 카카오로의 게임 데이터 전송도 중지합니다.
  • 동일 이벤트가 재수신될 수 있으므로 SET의 요청/토큰 식별자를 기준으로 멱등성을 보장합니다.
  • 사용자 정보가 없거나 이미 처리된 이벤트도 중복 처리 없이 정상 응답하는 것을 권장합니다.

연동 흐름 ​

통합서비스 약관 동의 철회

순서주체동작
1사용자통합서비스 약관 동의 철회
2카카오파트너사 앱 연결 해제 처리
3카카오계정 상태 변경 웹훅 발송 (reason = REVOKE_ACCOUNT_SERVICE_TERMS)
4파트너사SET 검증 → 데이터 파기·내부 상태 정리 → 디벨로퍼스 규격으로 응답

개별 앱 연결 해제·탈퇴

순서주체동작
1사용자카카오계정 페이지에서 앱 연결 해제 (또는 탈퇴 등)
2카카오계정 상태 변경 웹훅 발송 (reason = UNLINK_FROM_APPS 등)
3파트너사SET 검증 → 데이터 파기·내부 연결 상태 정리 → 디벨로퍼스 규격으로 응답

참고 문서 ​