๐Ÿ“ก ScapePulse Vote Callback System

Implementation guide for RSPS developers

๐Ÿ“‹ Overview

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.

๐Ÿ”—Auto-Vote URL Format (For External Toplists)

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:

https://scapepulse.com/vote/{SERVER_ID}/{INCENTIVE}
{SERVER_ID}
Your ScapePulse server ID number
{INCENTIVE}
Player username/identifier from toplist

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.

๐Ÿ”— Callback URL Format

ScapePulse uses a standard callback format with a unique vote identifier (UID):

Standard Format

https://yourserver.com/callback.php?uid=a1b2c3d4e5f6g7h8&voter_name=PlayerName

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.

๐Ÿ“ Callback Parameters

ParameterTypeDescriptionRequired
uidStringUnique identifier for this vote. Must be stored to prevent duplicate processing.Yes
voter_nameStringUsername/player name who voted (sanitized alphanumeric). Defaults to "anonymous" if not provided.No

๐Ÿ’ป PHP Implementation Example

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");
}
?>

โšก Key Implementation Notes

  • โ€ข The uid parameter is the unique vote identifier - store it to prevent duplicate processing
  • โ€ข Always check if a UID has already been processed before giving rewards
  • โ€ข Log all callback attempts for debugging and auditing
  • โ€ข Sanitize all input parameters to prevent SQL injection

๐Ÿ”’ Security Considerations

โœ… Best Practices

  • โ€ข Always use HTTPS for your callback URL
  • โ€ข Validate all input parameters
  • โ€ข Implement rate limiting
  • โ€ข Log all callback attempts
  • โ€ข Use database transactions
  • โ€ข Check for duplicate votes

โš ๏ธ Security Warnings

  • โ€ข Never trust user input without validation
  • โ€ข Don't expose database errors
  • โ€ข Avoid using public callback scripts
  • โ€ข Don't log sensitive information
  • โ€ข Implement proper error handling

๐Ÿงช Testing Your Callback

Admin Tool Available: Use our admin-only callback testing tool to verify your implementation.

  1. Configure your callback URL in your server settings
  2. Set up your callback handler script
  3. Use the admin testing tool to send test callbacks
  4. Verify votes are processed correctly
  5. Check your logs for any errors
  6. Test with different usernames and scenarios

๐Ÿ—„๏ธ Recommended Database Schema

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;

๐Ÿ”‘ Critical: UID Must Be Unique

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.

๐Ÿ’ฌ Support & Help

Need help implementing the callback system? Here are your options:

๐Ÿ“ง Contact Support

Email us with your technical questions and we'll help you get set up.

๐Ÿ”ง Testing Tool

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