๐Ÿ“ก 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.

๐Ÿ”— Callback URL Format

ScapePulse sends vote callbacks using the following format:

// Example callback URL
https://yourserver.com/callback.php?Kai=abc123def456789

Where Kai is the player's username andabc123def456789 is the unique vote identifier (UID).

๐Ÿ“ Callback Parameters

ParameterDescriptionFormat
Username (key)The player's username who votedAlphanumeric + underscores (1-64 chars)
UID (value)Unique identifier for this vote32-character hexadecimal string

๐Ÿ’ป PHP Implementation Example

Here's a complete PHP script to handle ScapePulse vote callbacks:

<?php
// ScapePulse Vote Callback Handler
include 'config.php';

// Database connection
$db = new PDO("mysql:host=$host;dbname=$database", $username, $password);

// Process all callback parameters
foreach ($_REQUEST as $player => $uid) {
    // Validate UID format (alphanumeric + underscores only)
    if (!preg_match('/^[a-zA-Z0-9_]+$/', $uid)) {
        error_log("Invalid UID format: " . $uid);
        continue;
    }
    
    // Validate username format
    if (!preg_match('/^[a-zA-Z0-9_]{1,64}$/', $player)) {
        error_log("Invalid username format: " . $player);
        continue;
    }
    
    // Check if vote already processed
    $stmt = $db->prepare("SELECT id FROM votes WHERE uid = ? AND processed = 1");
    $stmt->execute([$uid]);
    
    if ($stmt->rowCount() > 0) {
        error_log("Vote already processed: " . $uid);
        continue;
    }
    
    // Process the vote
    try {
        $db->beginTransaction();
        
        // Mark vote as processed
        $stmt = $db->prepare("
            INSERT INTO votes (player_name, uid, processed, vote_time, ip_address) 
            VALUES (?, ?, 1, NOW(), ?)
            ON DUPLICATE KEY UPDATE processed = 1
        ");
        $stmt->execute([$player, $uid, $_SERVER['REMOTE_ADDR']]);
        
        // Give reward to player (example: add 1000 GP)
        $stmt = $db->prepare("
            UPDATE player_data 
            SET coins = coins + 1000, vote_points = vote_points + 1 
            WHERE username = ?
        ");
        $stmt->execute([$player]);
        
        $db->commit();
        
        error_log("Vote processed successfully for " . $player . " (UID: " . $uid . ")");
        
    } catch (Exception $e) {
        $db->rollback();
        error_log("Error processing vote: " . $e->getMessage());
    }
}

// Return success response
http_response_code(200);
echo "OK";
?>

๐Ÿ”’ 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

-- Votes table to track callback processing
CREATE TABLE votes (
    id INT PRIMARY KEY AUTO_INCREMENT,
    player_name VARCHAR(64) NOT NULL,
    uid VARCHAR(32) NOT NULL UNIQUE,
    processed TINYINT DEFAULT 0,
    vote_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    ip_address VARCHAR(45),
    INDEX idx_player (player_name),
    INDEX idx_uid (uid),
    INDEX idx_processed (processed)
);

-- Player data table (example)
CREATE TABLE player_data (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(64) NOT NULL UNIQUE,
    coins BIGINT DEFAULT 0,
    vote_points INT DEFAULT 0,
    last_vote TIMESTAMP NULL
);

๐Ÿ’ฌ 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: 8/10/2025

Compatible with most PHP, Node.js, Python, and other web frameworks