- 마지막 업데이트
스토브 이벤트
이해하기
스토브 이벤트는 스토브 플랫폼에서 발생한 이용자 상태 변경을 게임 서버에 실시간으로 전달하는 시스템 이벤트예요.
아이디·비밀번호 변경, 로그인 수단 변경, 가입 국가 변경, 제재, 회원 탈퇴 신청, 게임 해지 신청·취소·완료처럼 계정 운영과 정책 처리에 영향을 주는 변경이 포함돼요. 게임사는 하나의 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 검증 절차
- 게임사는 Sandbox Callback URL과 인증 설정을 기술 담당자에게 전달해 등록해요.
- 기술 담당자와 협의한 테스트 계정·제재/해지 경로로 이벤트를 발생시켜요.
- 게임 서버는
event_reason·GUID, HTTP 200 응답과 대상 월드의 상태 반영을 확인해요.
기본 연동 구조
- Callback API 1개로 모든 이벤트 수신
- 스토브에는 게임당 Callback URL을 하나만 등록할 수 있어요. 모든 이벤트가 이 URL로 전달되며,
event_reason값으로 필요한 이벤트를 선별 처리해요. - 개별 월드 서버 등 여러 서버로 전파가 필요하면, 게임사 측에 브로커 서버를 두고 STOVE → 브로커 → 각 서버 구조로 구성해요.
- 스토브에는 게임당 Callback URL을 하나만 등록할 수 있어요. 모든 이벤트가 이 URL로 전달되며,
- 응답과 재전송
- 게임 서버는 정상 처리했거나 재처리할 수 있도록 저장한 뒤 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 설정 |
개발 흐름
- 수신·검증: 게임 서버는 등록한 인증 설정과 JSON 본문을 확인해요.
- 저장·응답: 게임 서버는 재처리할 수 있도록 이벤트를 저장한 뒤 HTTP 200을 응답해요. 저장 실패 시 오류를 응답해 재전송을 유도해요.
- 이용자 처리: 게임 서버는 GUID별로
event_reason·처리 이력·현재 상태를 확인해 멱등하게 처리해요. 알 수 없는 종류는 로그만 남겨요. - 내부 재처리: 응답 이후 처리 실패는 게임 서버의 재처리 큐로 관리해요.
중복·순서·전달 실패
ㆍ이벤트는 중복되거나 발생 순서와 다르게 도착할 수 있어요. 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로 수신하고, 중복·순서 변경을 고려해 멱등하게 처리해요.
설정 방법
- 게임사는 기술 담당자에게 적용 환경(Sandbox·Live),
game_id, 이벤트 종류, Callback URL과 DLQ 유효기간(초)을 전달해요. - STOVE 기술 담당자는 환경·게임·이벤트별 Callback 설정에 DLQ를 활성화하고 유효기간을 등록해요. 예를 들어 3,600초로 설정하면 최초 DLQ 진입부터 1시간 동안 추가 재전송해요.
- 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·이벤트 종류·발생 시각으로 기술 담당자에게 후속 처리 요청 |
샘플 코드
샘플은 이벤트 분기 예시예요. 운영 환경에서는 요청 인증, 수신 이벤트 저장·재처리와 멱등 처리를 구현해 주세요.
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 예시
{
"event_reason": "GAME_RESTRICT",
"event_message": "게임 이용이 제한되었어요.",
"event_time": 1765953754000,
"target_users": [
20005069331
]
}
자주 묻는 질문
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com