Skip to content
스토브
마지막 업데이트

실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 게임 해지하기

스토브 이벤트

이해하기


스토브 이벤트는 스토브 플랫폼에서 발생한 이용자 상태 변경을 게임 서버에 실시간으로 전달하는 시스템 이벤트예요.
아이디·비밀번호 변경, 로그인 수단 변경, 가입 국가 변경, 제재, 회원 탈퇴 신청, 게임 해지 신청·취소·완료처럼 계정 운영과 정책 처리에 영향을 주는 변경이 포함돼요. 게임사는 하나의 Callback API로 모든 이벤트를 수신하고, 이벤트 종류에 따라 운영 정책에 맞게 이용자 상태를 처리하면 돼요.

항목 내용
전달 방식 STOVE Event Broker → 게임사 Callback API (HTTPS POST, JSON)
수신 엔드포인트 게임당 1개 등록 (Sandbox·Live 분리)
이벤트 구분 Body의 event_reason 값
적용 대상 GUID 기반 서비스 게임
관련 가이드 게임 제재 · 게임 해지

적용 대상 및 제한 사항
ㆍ본 스토브 이벤트 기능은 GUID 기반 서비스 게임만 지원해요.
ㆍMember_no 기반 게임은 기본 지원 대상이 아니에요. 사용이 필요하면 기술 담당자를 통해 사전에 확인해 주세요.



제공 이벤트

현재 제공되는 이벤트는 아래와 같아요. 이벤트는 앞으로 계속 추가될 예정이므로, Callback API는 알 수 없는 event_reason 값을 받아도 오류 없이 200을 응답하도록 구현해 주세요.

이벤트 정보 이벤트 발생 상황 CP사 측 대응 가이드
① 계정 정보 변경
ACCOUNT_INFO_CHANGED
이용자가 로그인 수단을 변경(계정 전환)한 경우
이용자가 아이디를 변경한 경우 (영숫자 아이디 → 이메일 아이디, 미인증 이메일 → 다른 이메일 인증, 대문자 아이디 → 소문자 치환 등)
이용자가 가입 국가를 변경한 경우
이용자 로그아웃 및 게임 재시작 처리
② 비밀번호 변경
RESET_PASSWORD
이용자가 비밀번호를 변경한 경우 이용자 로그아웃 및 게임 재시작 처리
③ 스토브 제재
PLATFORM_RESTRICT
이용자가 스토브 플랫폼에서 제재된 경우 이용자 로그아웃 및 게임 재시작 처리
④ 스토브 회원 탈퇴 신청
PLATFORM_WITHDRAW
이용자가 스토브 플랫폼 회원 탈퇴를 신청한 경우 이용자 로그아웃 및 게임 재시작 처리
탈퇴 완료 후 데이터 정리는 게임 해지 / 스토브 회원 탈퇴 연동 참고
⑤ 원격 로그아웃
REMOTE_LOGOUT
이용자가 원격 로그아웃 기능을 실행한 경우 이용자 로그아웃 및 게임 재시작 처리
⑥ 게임 제재
GAME_RESTRICT
이용자가 게임에서 제재된 경우 이용자 로그아웃 및 게임 재시작 처리
상세: 게임 제재
⑦ 게임 해지 신청
GAME_WITHDRAW
이용자가 게임 해지를 신청한 경우 게임 서버의 이용자 상태를 해지 신청 상태로 업데이트, 세션 종료
상세: 게임 해지
⑧ 게임 해지 신청 취소
GAME_WITHDRAW_CANCEL
이용자가 게임 해지 신청을 취소한 경우 게임 서버의 이용자 상태를 정상 이용 가능 상태로 업데이트 (해지 신청 중 → 정상)
상세: 게임 해지
⑨ 게임 해지 완료
GAME_WITHDRAW_COMPLETE
이용자가 게임 해지를 완료한 경우
이용자가 플랫폼 회원 탈퇴를 완료한 경우 — 탈퇴 시 이용자가 가입된 모든 게임이 해지 처리돼요. 이용자가 직접 가입 절차를 거치지 않고 자동으로 가입된 게임도 포함되므로, 게임 서버에 가입·해지 신청 이력이 없는 이용자의 이벤트도 전달될 수 있어요.
게임 서버의 이용자 상태를 해지 완료로 업데이트, 세션 종료
데이터 삭제는 즉시 처리하지 않고 배치 등 운영 정책에 따라 수행
상세: 게임 해지

대응 가이드의 기본 원칙
ㆍ이용자 계정 상태가 바뀐 이벤트(①~⑥)는 현재 세션을 그대로 두면 안 되므로, 해당 이용자를 로그아웃하고 게임을 재시작하도록 처리해요.
ㆍ게임 해지 이벤트(⑦~⑨)는 게임 서버의 이용자 상태를 동기화하는 목적이에요. 데이터 삭제 시점과 방식은 게임 정책과 기술 담당자 협의에 따라요.
ㆍ정상 동선에서는 이용자가 이미 접속 불가 상태이지만, 장애·동기화 이슈에 대비해 서버 차단 처리도 함께 권장해요.



이벤트 처리 흐름

이용자 상태 변경의 원인이 무엇이든 처리 흐름은 같아요. 스토브 플랫폼이 상태 변경을 처리하면 Event Broker가 게임 서버의 Callback API를 호출하고, 게임 서버는 이벤트 종류에 맞게 이용자를 처리해요.

인게임 이벤트 처리
ㆍ아이디·비밀번호 변경, 회원 탈퇴 신청, 원격 로그아웃, 제재는 모두 같은 Callback API로 전달되고 같은 방식으로 처리돼요.
ㆍ게임 정책에 따라 처리가 달라지는 이벤트(계정 정보 변경 등)는 게임사 정책에 맞게 처리하면 돼요.

연동 가이드


사전 준비

항목 내용
이용자 식별 방식 확인 GUID 기반 서비스만 지원. Member_no 기반이면 기술 담당자에게 사전 확인
Callback API 구현 HTTPS POST 수신 엔드포인트 구현. Sandbox·Live용 도메인 각각 준비
Callback URL 등록 기술 담당자에게 환경별 URL 등록 요청
네트워크 허용 Inbound ACL·방화벽이 있으면 STOVE Event Broker의 환경별 NAT IP 허용 (IP는 기술 담당자 문의)
처리 대상 이벤트 결정 모든 이벤트 처리가 원칙. 게임 정책상 특정 이벤트 on/off가 필요하면 기술 담당자와 사전 협의



Sandbox 검증 절차

  1. 게임사는 Sandbox Callback URL과 인증 설정을 기술 담당자에게 전달해 등록해요.
  2. 기술 담당자와 협의한 테스트 계정·제재/해지 경로로 이벤트를 발생시켜요.
  3. 게임 서버는 event_reason·GUID, HTTP 200 응답과 대상 월드의 상태 반영을 확인해요.



기본 연동 구조

  • Callback API 1개로 모든 이벤트 수신
    • 스토브에는 게임당 Callback URL을 하나만 등록할 수 있어요. 모든 이벤트가 이 URL로 전달되며, event_reason 값으로 필요한 이벤트를 선별 처리해요.
    • 개별 월드 서버 등 여러 서버로 전파가 필요하면, 게임사 측에 브로커 서버를 두고 STOVE → 브로커 → 각 서버 구조로 구성해요.
  • 응답과 재전송
    • 게임 서버는 정상 처리했거나 재처리할 수 있도록 저장한 뒤 HTTP 200을 응답해요. STOVE는 통신 실패·오류 응답·타임아웃 시 등록된 정책에 따라 재전송해요.
    • 같은 이벤트가 중복 전달될 수 있어요. 게임 서버는 이벤트 종류·GUID별 처리 이력과 현재 상태를 확인해 멱등하게 처리해요.
  • 이벤트 처리 정책
    • 전달되는 모든 이벤트를 처리하는 것이 원칙이에요. 게임 정책상 특정 이벤트를 켜고 끌 필요가 있으면 적용 범위와 처리 방식을 기술 담당자와 사전에 협의해요.

이벤트는 이용자(GUID) 단위로 전달돼요
ㆍ콜백 본문(event_reason·event_message·event_time·target_users)에는 월드·캐릭터 구분값이 없어요. target_users의 GUID로 대상 이용자가 속한 월드·캐릭터를 게임 서버에서 판별해야 해요.
ㆍ권역별 월드(예: 리전별 world_id)로 운영하는 게임도 Callback URL은 1개예요. 게임사 측 브로커 서버가 이벤트를 받아 해당 리전·월드 서버로 전파하는 구조를 권장해요.


이벤트 처리 시퀀스 (예시)

이건 꼭 알아 두세요
ㆍ스토브 서버와 게임 서버 사이에 Inbound ACL이 있다면 STOVE Event Broker의 환경별 NAT IP를 허용해야 해요. IP는 기술 담당자에게 문의해 주세요.
ㆍSandbox와 Live 환경의 Callback 도메인은 반드시 분리해서 등록해요.
ㆍ요청 인증은 개발하기의 요청 인증 안내에 따라 등록 시 확인해요.

개발하기


Callback API 구성 가이드

게임사가 직접 구현해 운영하는 엔드포인트예요. STOVE Event Broker가 이벤트 발생 시 이 URL을 호출해요.

사전 준비

항목 내용
URL CP사 제공 (예: https://{server-domain}/callback). 경로는 자유롭게 정의
Method POST
Protocol HTTPS (TLS 1.2 이상)
Content-Type application/json
등록 방법 기술 담당자에게 환경별 URL·인증 설정 전달 후 Sandbox 검증 진행
등록 개수 게임당 1개. 본문에 월드 정보가 없으므로 게임 서버가 GUID로 대상 월드를 판별해 전파
재전송 정책 실패 시 기본 3초 간격으로 최대 3회 재전송 (최초 전송 제외). 실제 간격·횟수는 등록 시 기술 담당자에게 확인
요청 인증 등록 설정에 따라 Authorization 헤더 전달. 사용 여부·인증값은 등록 시 협의하고 게임 서버에서 검증
통신 제한 시간 연결·읽기·쓰기 각각 3초 (전체 처리 시간의 상한과는 다름). 게임 서버는 처리·저장을 마친 뒤 빠르게 HTTP 200 응답
추가 재전송 (선택 사항) 기본 재전송 실패 후 유효기간 동안 30초 간격으로 추가 전송. 환경·게임·이벤트별 DLQ 설정

개발 흐름

  1. 수신·검증: 게임 서버는 등록한 인증 설정과 JSON 본문을 확인해요.
  2. 저장·응답: 게임 서버는 재처리할 수 있도록 이벤트를 저장한 뒤 HTTP 200을 응답해요. 저장 실패 시 오류를 응답해 재전송을 유도해요.
  3. 이용자 처리: 게임 서버는 GUID별로 event_reason·처리 이력·현재 상태를 확인해 멱등하게 처리해요. 알 수 없는 종류는 로그만 남겨요.
  4. 내부 재처리: 응답 이후 처리 실패는 게임 서버의 재처리 큐로 관리해요.

중복·순서·전달 실패
ㆍ이벤트는 중복되거나 발생 순서와 다르게 도착할 수 있어요. target_users를 처리하고, 요청당 100명 고정 묶음을 전제하지 않아요.
ㆍ기본 재전송이 모두 실패하면 활성화한 DLQ에서 유효기간 동안 추가 전송해요. DLQ 설정 방법을 참고해 주세요.

Request — Body 명세

Name Type Required Description
event_reason String Y 이벤트 종류. 제공 이벤트 표의 코드 값 (예: REMOTE_LOGOUT)
event_message String Y 이용자 안내용 메시지. 게임 언어와 다를 수 있으므로 게임의 언어·운영 정책에 맞게 표시
event_time Long Y 이벤트 발생 시각. Unix epoch (1970-01-01 00:00:00 UTC) 기준 밀리초.
target_users Long Array Y 대상 GUID 목록 (최대 100명). 월드·캐릭터 정보는 게임 서버에서 판별

Response

응답 형식은 게임 서버 구조에 맞게 자유롭게 구현하면 돼요. 단, 정상 수신 시에는 반드시 HTTP Status Code 200으로 응답해야 해요.

저장한 뒤 응답해 주세요
ㆍ게임 서버는 정상 처리했거나 재처리 가능한 저장을 마친 뒤 HTTP 200을 응답해요. 수신 데이터를 저장하지 못했다면 성공으로 응답하지 마세요.


추가 재전송 (선택 사항)

추가 재전송 DLQ(Dead Letter Queue)는 기본 재전송이 모두 실패한 이벤트를 별도 큐에 보관하고, 게임 서버의 Callback API로 자동 재전송하는 기능이에요.

  • 재전송: 설정한 유효기간 동안 원본 이벤트를 30초 간격으로 다시 전송해요.
  • 종료: 전송에 성공하면 종료하고, 유효기간이 만료되면 최종 실패로 기록해요.
  • 처리: 게임 서버는 일반 이벤트와 같은 Callback API로 수신하고, 중복·순서 변경을 고려해 멱등하게 처리해요.

설정 방법

  1. 게임사는 기술 담당자에게 적용 환경(Sandbox·Live), game_id, 이벤트 종류, Callback URL과 DLQ 유효기간(초)을 전달해요.
  2. STOVE 기술 담당자는 환경·게임·이벤트별 Callback 설정에 DLQ를 활성화하고 유효기간을 등록해요. 예를 들어 3,600초로 설정하면 최초 DLQ 진입부터 1시간 동안 추가 재전송해요.
  3. Sandbox에서 Callback API에 오류를 응답해 기본 재전송 이후 DLQ 전송을 확인하고, HTTP 200 응답으로 전환해 재전송이 종료되는지 확인해요.

DLQ는 STOVE에서 Callback API까지의 전송 실패를 처리해요. HTTP 200 응답 이후 게임 서버 내부의 처리 실패는 게임 서버의 재처리 큐로 관리해요.


트러블슈팅

상황 원인 해결 방법
이벤트가 수신되지 않아요 Callback URL 미등록 또는 잘못된 URL 등록 기술 담당자에게 등록 URL과 환경(Sandbox/Live) 재확인 요청
이벤트가 수신되지 않아요 ACL/방화벽에서 스토브 NAT IP 차단 환경별 NAT IP가 Inbound 허용 목록에 있는지 점검
같은 이벤트가 여러 번 수신돼요 통신 실패·4xx/5xx·타임아웃으로 재전송됨 처리·저장 성공 시 HTTP 200 응답. 이후 처리 실패는 내부 재처리 큐로 관리
같은 이벤트가 여러 번 수신돼요 네트워크 이슈로 인한 중복 전송 이벤트 종류·GUID별 처리 이력과 현재 상태를 확인해 멱등 처리
일부 이벤트만 처리하고 싶어요 모든 이벤트가 하나의 Callback으로 전달됨 event_reason으로 분기해 필요한 이벤트만 처리. 미처리 이벤트도 200 응답은 반환
여러 월드 서버에 전파해야 해요 STOVE에는 Callback URL을 1개만 등록 가능 게임 서버가 GUID로 소속 리전·월드를 판별하고 브로커를 통해 해당 서버로 전파
응답 지연으로 재전송돼요 연결·읽기·쓰기 제한 시간 (각 3초) 초과 게임 서버는 수신 이벤트를 저장한 뒤 HTTP 200을 응답하고 실제 처리는 분리
기본 재전송이 모두 실패했어요 게임 서버 장애 또는 연결 오류 지속 DLQ를 활성화해 유효기간 동안 추가 전송. 만료 시 환경·game_id·GUID·이벤트 종류·발생 시각으로 기술 담당자에게 후속 처리 요청

샘플 코드

샘플은 이벤트 분기 예시예요. 운영 환경에서는 요청 인증, 수신 이벤트 저장·재처리와 멱등 처리를 구현해 주세요.

bash
curl --location 'https://{server-domain}/callback' \
--header 'Content-Type: application/json' \
--data '{
    "event_reason": "REMOTE_LOGOUT",
    "event_message": "원격 로그아웃되었어요. 다시 로그인해 주세요.",
    "event_time": 1765953754000,
    "target_users": [20005069331]
}'

이벤트별 Body 예시

json
{
    "event_reason": "GAME_RESTRICT",
    "event_message": "게임 이용이 제한되었어요.",
    "event_time": 1765953754000,
    "target_users": [
        20005069331
    ]
}

자주 묻는 질문



Q1. 이벤트 종류마다 Callback API를 따로 만들어야 하나요?
A. 아니요. 스토브에는 게임당 Callback URL을 하나만 등록하며, 모든 이벤트가 그 URL로 전달돼요.
Body의 event_reason 값으로 분기해 필요한 이벤트만 처리하면 돼요.
Q2. 처리하지 않는 이벤트를 받으면 어떻게 응답해야 하나요?
A. 알 수 없거나 처리 대상이 아닌 이벤트는 HTTP 200을 응답해 주세요. 처리 대상 이벤트는 정상 처리 또는 재처리 가능한 저장을 마친 뒤 HTTP 200을 응답해요.
Q3. 같은 이벤트가 여러 번 들어와요. 왜 그런가요?
A. 통신 실패·오류 응답·타임아웃으로 재전송될 수 있어요. 게임 서버는 이벤트 종류·GUID별 처리 이력과 현재 상태를 확인해 멱등하게 처리해요. event_time만으로 중복·처리 순서를 판단하지 마세요.
Q4. PLATFORM_WITHDRAW 이벤트를 받으면 어떻게 처리해야 하나요?
A. 이용자가 스토브 플랫폼 탈퇴를 신청한 시점에 전달되는 이벤트예요.
수신 시 해당 이용자를 인게임에서 로그아웃 처리해 주세요.
탈퇴가 완료되면 가입된 게임별로 GAME_WITHDRAW_COMPLETE(⑨)가 전달되므로, 게임 해지 완료와 동일하게 데이터를 정리하면 돼요. 자세한 내용은 게임 해지 / 스토브 회원 탈퇴 연동을 참고해 주세요.
Q5. GAME_WITHDRAW, GAME_WITHDRAW_CANCEL, GAME_WITHDRAW_COMPLETE 이벤트는 어떤 용도인가요?
A. 세 이벤트 모두 게임 서버의 이용자 상태를 동기화하기 위한 이벤트예요.
GAME_WITHDRAW는 해지 신청 시, GAME_WITHDRAW_CANCEL은 신청 취소 시, GAME_WITHDRAW_COMPLETE는 해지 완료 시 전달돼요.
유예기간을 두고 해지하는 경우 여러 서버 간 해지 상태를 동기화하는 데 활용할 수 있어요. 게임 정책에 따라 처리 방식을 결정해 주세요.
Q6. Member_no 기반 게임도 스토브 이벤트를 받을 수 있나요?
A. 기본 지원 대상은 GUID 기반 서비스 게임이에요.
Member_no 기반 게임에서 사용이 필요하면 기술 담당자를 통해 사전에 확인해 주세요.
Q7. 기본 재전송이 모두 실패하면 어떻게 되나요?
A. DLQ를 활성화하면 유효기간 동안 30초 간격으로 추가 전송해요. 전송 성공 시 종료하고, 유효기간 만료 시 최종 실패로 기록해요. 설정은 DLQ 설정 방법을 참고해 주세요.



문의가 필요하신가요?