---
url: /api-sdk/data/terms-withdrawal-migration.md
description: 기존 약관 동의 철회 통지 API를 카카오 로그인 계정 상태 변경 웹훅으로 전환하기 위한 마이그레이션 전용 가이드
---

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

::: info 디벨로퍼스 마이그레이션 가이드
이 문서는 기존 약관 동의 철회 통지 API(파트너사 자체 구현 콜백)를 카카오디벨로퍼스 [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf)으로 전환하기 위한 **마이그레이션 전용 가이드**입니다. 앞으로 제공될 디벨로퍼스 문서로 대체될 예정이며, 그때까지만 제공됩니다. 전환을 마친 뒤의 최신 규격은 [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)을 참고하세요.
:::

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

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

> **관련 가이드**: [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정, [카카오싱크 API](/api-sdk/kakaosync/rest-api): 연결 해제 요청, [심사 체크리스트](/docs/checklist/review-checklist): 철회 처리 자체 점검 항목

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

## 변경 개요

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

## 연동 대상

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

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

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

## 인증

SET 서명 검증 등 요청 인증·검증 규격은 디벨로퍼스 [계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf) 문서를 따릅니다.

요청 본문(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를 호출하지 않은 경우입니다 | 생성된 임시 데이터가 있다면 파기 |

::: tip 핵심 변경점
기존에는 약관 철회 통지를 받은 뒤 파트너사가 직접 앱 연결 해제와 데이터 파기를 함께 처리했습니다. 웹훅 전환 후에는 `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 검증 → 데이터 파기·내부 연결 상태 정리 → 디벨로퍼스 규격으로 응답 |

## 참고 문서

* [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 전환 후 최신 규격
* [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf): SET 구조·검증·응답 규격
* [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정
* [카카오싱크 API](/api-sdk/kakaosync/rest-api): 서비스 탈퇴와 연결 해제 요청
* [심사 체크리스트](/docs/checklist/review-checklist)
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)