Skip to content
Stove
Cập nhật lần cuối

Are you curious about the actual implementation flow?

Usage Scenario / Unsubscribing from a Game

STOVE Events

Understanding


STOVE Events are system events that deliver user status changes occurring on the STOVE platform to your game server in real time.
This includes changes that affect account operations and policy processing, such as ID/password changes, login method changes, country of residence changes, sanctions, withdrawal requests, and game unsubscription requests/cancellations/completions. Game companies can receive all events through a single Callback API and process user statuses according to their operational policies based on the event type.

Item Description
Delivery Method STOVE Event Broker → Game Company Callback API (HTTPS POST, JSON)
Receiving Endpoint 1 per game (Sandbox/Live separated)
Event Classification The event_reason value in the Body
Applicable Targets GUID-based service games
Related Guides Game Sanctions · Game Unsubscription

Applicable Targets and Restrictions
ㆍThis STOVE Event feature is only supported for GUID-based service games.
ㆍMember_no-based games are not supported by default. If you need to use this, please check with your technical representative in advance.



Provided Events

The currently provided events are as follows. As events will continue to be added in the future, please implement your Callback API to respond with 200 without errors even if it receives an unknown event_reason value.

Event Information Event Occurrence Situation CP Response Guide
① Account Information Changed
ACCOUNT_INFO_CHANGED
When the user changes their login method (account switch)
When the user changes their ID (alphanumeric ID → email ID, unverified email → other verified email, uppercase ID → lowercase substitution, etc.)
When the user changes their country of registration
Process user logout and game restart
② Password Changed
RESET_PASSWORD
When the user changes their password Process user logout and game restart
③ Stove Restriction
PLATFORM_RESTRICT
When the user is restricted on the Stove platform Process user logout and game restart
④ Stove Membership Withdrawal Request
PLATFORM_WITHDRAW
When the user requests withdrawal from the Stove platform Process user logout and game restart
For data cleanup after withdrawal, please refer to Game Unsubscription / Stove Membership Withdrawal Integration.
⑤ Remote Logout
REMOTE_LOGOUT
When the user executes the remote logout function Process user logout and game restart
⑥ Game Restriction
GAME_RESTRICT
When the user is restricted in the game Process user logout and game restart
Details: Game Restriction
⑦ Game Unsubscription Request
GAME_WITHDRAW
When the user requests game unsubscription Update user status on the game server to unsubscription requested, terminate session
Details: Game Unsubscription
⑧ Cancel Game Unsubscription Request
GAME_WITHDRAW_CANCEL
When the user cancels the game unsubscription request Update user status on the game server to normal available status (unsubscription requested → normal)
Details: Game Unsubscription
⑨ Game Unsubscription Complete
GAME_WITHDRAW_COMPLETE
When the user completes game unsubscription
When the user completes platform membership withdrawal — all games the user is subscribed to are unsubscribed upon withdrawal. This includes games that were automatically subscribed without the user going through the sign-up process, so events for users who have no record of sign-up/unsubscription requests on the game server may also be delivered.
Update the user status on the game server to 'cancellation complete' and terminate the session.
Data deletion is not processed immediately but is performed according to operational policies such as batch processing.
Details: Game Cancellation

Basic Principles of the Response Guide
ㆍFor events where the user account status has changed (①–⑥), do not leave the current session as is; process the user to log out and restart the game.
ㆍGame cancellation events (⑦–⑨) are intended to synchronize the user status on the game server. The timing and method of data deletion depend on game policies and consultations with technical staff.
ㆍIn a normal flow, the user is already in an inaccessible state, but server-side blocking is also recommended to prepare for failures or synchronization issues.



Event Processing Flow

Regardless of the cause of the user status change, the processing flow is the same. Once the Stove platform processes the status change, the Event Broker calls the game server's Callback API, and the game server processes the user according to the event type.

In-game Event Handling
ㆍChanges to ID/password, account deletion requests, remote logouts, and sanctions are all delivered via the same Callback API and processed in the same manner.
ㆍEvents that require handling based on game policy (such as account information changes) should be processed according to your game's specific policies.

Integration Guide


Prerequisites

Item Description
Verify User Identification Method Only supports GUID-based services. If using Member_no, check with the technical representative in advance.
Implement Callback API Implement an HTTPS POST receiving endpoint. Prepare separate domains for Sandbox and Live environments.
Register Callback URL Request registration of URLs for each environment to the technical representative.
Network Allowlisting If there is an Inbound ACL or firewall, allow the NAT IP of the STOVE Event Broker for each environment (inquire with the technical representative for the IP).
Determine Events to Process The principle is to process all events. If specific event on/off toggles are needed due to game policy, consult with the technical representative in advance.



Sandbox Verification Procedure

  1. The game company provides the Sandbox Callback URL and authentication settings to the technical representative for registration.
  2. Trigger events using the test account and sanction/revocation paths discussed with the technical representative.
  3. The game server verifies event_reason, GUID, HTTP 200 response, and the reflection of the target world's status.



Basic Integration Structure

  • Receive all events with 1 Callback API
    • Only one Callback URL can be registered per game in STOVE. All events are delivered to this URL, and you select and process the necessary events using the event_reason value.
    • If propagation to multiple servers (such as individual world servers) is required, we recommend a structure where the game company operates a broker server: STOVE → Broker → Each Server.
  • Response and Retransmission
    • The game server should respond with HTTP 200 after successfully processing or saving the event for reprocessing. STOVE will retransmit according to the registered policy in case of communication failure, error response, or timeout.
    • The same event may be delivered multiple times. The game server must ensure idempotent processing by checking the processing history and current status for each event type and GUID.
  • Event Handling Policy
    • The principle is to process all delivered events. If you need to turn specific events on or off based on game policy, discuss the scope and processing method with the technical representative in advance.

Events are delivered per user (GUID)
ㆍThe callback body (event_reason, event_message, event_time, target_users) does not contain world or character identifiers. The game server must determine the world or character to which the target user belongs using the GUID in target_users.
ㆍEven for games operating with world servers by region (e.g., world_id per region), there is only one Callback URL. We recommend a structure where the game company's broker server receives the event and propagates it to the corresponding region/world server.


Event Processing Sequence (Example)

Important Notes
ㆍIf there is an Inbound ACL between the STOVE server and the game server, you must allow the NAT IP of the STOVE Event Broker for each environment. Please inquire with the technical representative for the IP.
ㆍCallback domains for Sandbox and Live environments must be registered separately.
ㆍRequest authentication is verified during registration according to the Request Authentication in Development guide.

Development


Callback API Configuration Guide

This is an endpoint implemented and operated directly by the game company. The STOVE Event Broker calls this URL when an event occurs.

Prerequisites

Item Content
URL Provided by CP (e.g., https://{server-domain}/callback). Path can be defined freely
Method POST
Protocol HTTPS (TLS 1.2 or higher)
Content-Type application/json
Registration Method After providing the environment-specific URL and authentication settings to the technical manager, Sandbox verification proceeds
Number of Registrations 1 per game. Since there is no world information in the body, the game server identifies and propagates the target world via GUID.
Retry Policy In case of failure, retry up to 3 times at 3-second intervals by default (excluding initial transmission). Confirm actual intervals and counts with the technical manager upon registration.
Request Authentication Depending on registration settings, Authorization header is passed. Usage and authentication values should be discussed during registration and verified by the game server.
Communication Timeout 3 seconds each for connection, read, and write (different from the upper limit of total processing time). The game server should respond with HTTP 200 quickly after completing processing and storage.
Additional Retry (Optional) After default retry failure, additional transmissions occur at 30-second intervals during the validity period. DLQ settings by environment, game, and event

Development Flow

  1. Reception/Verification: The game server checks the registered authentication settings and JSON body.
  2. Storage/Response: The game server stores the event for reprocessing and responds with HTTP 200. If storage fails, it responds with an error to trigger a retry.
  3. User Processing: The game server checks event_reason, processing history, and current status by GUID to process idempotently. Unknown types are only logged.
  4. Internal Reprocessing: Processing failures after the response are managed by the game server's reprocessing queue.

Duplication, Order, and Delivery Failure
ㆍEvents may arrive duplicated or out of order. Process target_users and do not assume a fixed batch of 100 people per request.
ㆍIf all default retries fail, additional transmissions occur during the validity period from the activated DLQ. Please refer to DLQ setup method.

Request — Body Specification

Name Type Required Description
event_reason String Y Event type. Code value from the provided event table (e.g., REMOTE_LOGOUT).
event_message String Y Message for user notification. May differ from the game language, so display it according to the game's language and operational policies.
event_time Long Y Time of event occurrence. Milliseconds based on Unix epoch (1970-01-01 00:00:00 UTC).
target_users Long Array Y List of target GUIDs (up to 100). World/character information is determined by the game server.

Response

The response format can be implemented freely to suit the game server structure. However, you must respond with an HTTP Status Code 200 upon successful receipt.

Please respond after saving
ㆍThe game server should respond with HTTP 200 after successfully processing or saving the data for potential reprocessing. Do not respond with success if you failed to save the received data.


Additional Retransmission (Optional)

The additional retransmission DLQ (Dead Letter Queue) is a feature that stores events for which all default retransmissions have failed in a separate queue and automatically retransmits them to the game server's Callback API.

  • Retransmission: Retransmits the original event at 30-second intervals for the configured validity period.
  • Termination: Terminates upon successful transmission, and records as a final failure if the validity period expires.
  • Processing: The game server receives it via the same Callback API as regular events and processes it idempotently, considering duplication and order changes.

Configuration Method

  1. The game company provides the application environment (Sandbox/Live), game_id, event type, Callback URL, and DLQ validity period (seconds) to the technical representative.
  2. The STOVE technical representative enables DLQ in the Callback settings for each environment, game, and event, and registers the validity period. For example, if set to 3,600 seconds, additional retransmissions will occur for 1 hour from the initial entry into the DLQ.
  3. Verify DLQ transmission after default retransmission by responding with an error to the Callback API in the Sandbox, and confirm that retransmission terminates upon switching to an HTTP 200 response.

DLQ handles transmission failures from STOVE to the Callback API. Processing failures within the game server after an HTTP 200 response are managed by the game server's own reprocessing queue.


Troubleshooting

Situation Cause Solution
Events are not being received Callback URL not registered or incorrect URL registered Request the technical representative to re-verify the registered URL and environment (Sandbox/Live)
Events are not being received Stove NAT IP blocked by ACL/firewall Check if the NAT IP for each environment is in the Inbound allow list
The same event is received multiple times Retransmitted due to communication failure, 4xx/5xx errors, or timeouts Return HTTP 200 upon successful processing/storage. Manage subsequent processing failures with an internal retry queue
The same event is received multiple times Duplicate transmission due to network issues Check processing history and current status by event type/GUID to perform idempotent processing
I only want to process some events All events are delivered to a single Callback event_reasonBranch by event_reason to process only necessary events. Return 200 even for unprocessed events
I need to propagate to multiple world servers Only one Callback URL can be registered in STOVE The game server identifies the target region/world by GUID and propagates it to the corresponding server via a broker
Retransmitted due to response delay Connection/read/write timeout (3 seconds each) exceeded The game server should store the received event, return HTTP 200, and separate the actual processing
All default retries have failed Persistent game server failure or connection error Enable DLQ for additional transmission during the validity period. Upon expiration, request follow-up processing from the technical representative with the environment, game_id, GUID, event type, and occurrence time

Sample Code

The sample is an example of event branching. In a production environment, please implement request authentication, received event storage/re-processing, and idempotent processing.

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]
}'
Q1. Do I need to create a separate Callback API for each event type?
A. No. Only one Callback URL per game is registered in Stove, and all events are delivered to that URL.
You can branch based on the event_reason value in the Body to process only the necessary events.
Q2. How should I respond if I receive an event that I do not process?
A. Please respond with HTTP 200 for events that are unknown or not subject to processing. For events that are subject to processing, respond with HTTP 200 after completing normal processing or saving them for reprocessing.
Q3. The same event is coming in multiple times. Why is that?
A. It may be retransmitted due to communication failure, error response, or timeout. The game server should check the processing history and current status by event type and GUID to process it idempotently.event_time Do not judge duplication or processing order based solely on.
Q4. How should I process the PLATFORM_WITHDRAW event when I receive it?
A. This is an event delivered at the time a user requests to withdraw from the Stove platform.
Please process the logout of the user in-game upon receipt.
When the withdrawal is complete, GAME_WITHDRAW_COMPLETE(⑨) is delivered for each subscribed game, so you can clean up the data in the same way as completing a game cancellation. For more details, please refer to Game Cancellation / Stove Membership Withdrawal Integration.
Q5. What are the GAME_WITHDRAW, GAME_WITHDRAW_CANCEL, and GAME_WITHDRAW_COMPLETE events used for?
A. All three events are for synchronizing user status on the game server.
GAME_WITHDRAW is delivered upon cancellation request, GAME_WITHDRAW_CANCEL upon cancellation of the request, and GAME_WITHDRAW_COMPLETE upon completion of the cancellation.
If you are cancelling with a grace period, you can use it to synchronize the cancellation status between multiple servers. Please decide the processing method according to your game policy.
Q6. Can Member_no-based games also receive Stove events?
A. The basic support target is GUID-based service games.
If you need to use it in a Member_no-based game, please check with your technical representative in advance.
Q7. What happens if all basic retransmissions fail?
A. If you enable DLQ, it will be retransmitted at 30-second intervals during the validity period. It ends upon successful transmission and is recorded as a final failure when the validity period expires. For settings, please refer to How to set up DLQ.



Do you need an inquiry?