Implementation guide for RSPS developers
The ScapePulse callback system allows your RuneScape Private Server to automatically verify votes and reward players when they vote for your server on our platform.
When a player votes for your server, ScapePulse sends a secure callback to your server with a unique identifier. Your server can then process this callback to give rewards to the player.
When registering your server on external toplists (RuneLocus, Rune-Server, etc.), use this URL format to send players to ScapePulse with the proper UID passthrough:
Example: https://scapepulse.com/vote/42/PlayerName
This URL will preserve the UID from external toplists and pass it through to your callback handler, ensuring vote tracking works correctly across all platforms.
ScapePulse uses a standard callback format with a unique vote identifier (UID):
The uid parameter contains a unique identifier for the vote, and voter_name contains the player's username (if provided).
Important: When receiving votes from external toplist sites (RuneLocus, Rune-Server, etc.), the UID parameter will contain the exact same value that was sent from that site. You must store and verify this UID to prevent duplicate votes.
| Parameter | Type | Description | Required |
|---|---|---|---|
| uid | String | Unique identifier for this vote. Must be stored to prevent duplicate processing. | Yes |
| voter_name | String | Username/player name who voted (sanitized alphanumeric). Defaults to "anonymous" if not provided. | No |
Here's a complete PHP implementation that handles ScapePulse vote callbacks:
<?php
/**
* ScapePulse Vote Callback Handler
* Place this file on your server and configure the URL in your ScapePulse server settings
*/
// Database configuration
include 'constants.php';
include 'classes/class.database.php';
$db = new Database(db_host, db_user, db_pass, db_data);
if (!$db->connect()) {
error_log(date('[Y-m-d H:i:s]') . " Database connection failed" . PHP_EOL, 3, "logs.txt");
exit;
}
// Get callback parameters
$uid = isset($_REQUEST['uid']) ? $_REQUEST['uid'] : null;
$voter_name = isset($_REQUEST['voter_name']) ? $_REQUEST['voter_name'] : 'anonymous';
// Validate UID
if (!$uid) {
error_log(date('[Y-m-d H:i:s]') . " No UID provided" . PHP_EOL, 3, "logs.txt");
exit;
}
// Clean input
$uid = preg_replace('/[^a-zA-Z0-9_\-\.]/', '', $uid);
$voter_name = preg_replace('/[^a-zA-Z0-9_]/', '', $voter_name);
// Check if this vote has already been processed (prevent duplicates)
$existingVote = $db->getVoteByUid($uid);
if ($existingVote != null) {
error_log(date('[Y-m-d H:i:s]') . " Duplicate vote attempt for UID: $uid" . PHP_EOL, 3, "logs.txt");
echo json_encode(['success' => false, 'error' => 'Vote already processed']);
exit;
}
// Process the vote
$voteData = [
'uid' => $uid,
'voter_name' => $voter_name,
'vote_time' => time(),
'ip_address' => $_SERVER['REMOTE_ADDR'] ?? 'unknown',
'processed' => 1
];
// Insert vote into database
$result = $db->insertVote($voteData);
if ($result) {
error_log(date('[Y-m-d H:i:s]') . " Successfully processed vote - UID: $uid, Player: $voter_name" . PHP_EOL, 3, "logs.txt");
// Give rewards to the player (if not anonymous)
if ($voter_name && $voter_name !== 'anonymous') {
giveVotingRewards($voter_name);
}
echo json_encode(['success' => true, 'message' => 'Vote processed']);
} else {
error_log(date('[Y-m-d H:i:s]') . " Failed to insert vote - UID: $uid" . PHP_EOL, 3, "logs.txt");
echo json_encode(['success' => false, 'error' => 'Database error']);
}
/**
* Give voting rewards to a player
*/
function giveVotingRewards($playerName) {
// Example: Give vote points, items, or other rewards
// Implement according to your server's reward system
// Example:
// $db->addVotePoints($playerName, 1);
// $db->addItem($playerName, 995, 100000); // 100k coins
error_log(date('[Y-m-d H:i:s]') . " Gave voting rewards to: $playerName" . PHP_EOL, 3, "logs.txt");
}
?>uid parameter is the unique vote identifier - store it to prevent duplicate processingAdmin Tool Available: Use our admin-only callback testing tool to verify your implementation.
Use this schema to track votes and prevent duplicate processing:
-- Votes table to track callback processing
CREATE TABLE votes (
id INT PRIMARY KEY AUTO_INCREMENT,
uid VARCHAR(64) NOT NULL UNIQUE, -- MUST be unique to prevent duplicates
voter_name VARCHAR(64) DEFAULT 'anonymous',
vote_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
ip_address VARCHAR(45),
processed TINYINT DEFAULT 1,
INDEX idx_uid (uid), -- Fast lookup for duplicate checking
INDEX idx_voter (voter_name),
INDEX idx_vote_time (vote_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- Player data table (example - customize for your server)
CREATE TABLE player_data (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(64) NOT NULL UNIQUE,
vote_points INT DEFAULT 0,
total_votes INT DEFAULT 0,
last_vote TIMESTAMP NULL,
INDEX idx_username (username)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;The uid column MUST have a UNIQUE constraint. This ensures that if ScapePulse (or an external toplist) sends the same vote callback twice, your database will reject the duplicate and prevent double-rewarding players.
Need help implementing the callback system? Here are your options:
Email us with your technical questions and we'll help you get set up.
Use our admin testing interface to verify your callback implementation.
ScapePulse Callback System Documentation โข Last updated: 10/1/2025
Compatible with most PHP, Node.js, Python, and other web frameworks