Callback Documentation

When a player votes for your server on RSPS.org, we send a callback to your server with their username and IP. You verify the secret, reward the player, and return HTTP 200. The whole round-trip takes about a second. Below is everything you need to wire it up, plus working examples in PHP, Node, and Java.

List Your Server

Submit your server, then grab a callback URL and a private secret from your dashboard. Both are tied to your listing and can be regenerated any time.

Add the Endpoint

Drop a route on your server that checks the secret, reads the username, and rewards the player. Examples in three languages below.

Get Verified Votes

Each callback ties one vote to a real player and IP. Bots and duplicate traffic are filtered before they reach your ranking.

How Callbacks Work

Our toplist sends a GET request to your callback URL whenever a player votes:

https://yourdomain.com/vote/callback?callback=Player123&ip=1.2.3.4&secret=YOUR_SECRET

The request contains the following parameters:

callback
The player's username or unique identifier you passed in the voting link.
ip
The IP address of the voter.
secret
Your private secret key to verify that the request is legitimate.

Your backend should:

  • Validate that the secret matches your configured toplist secret.
  • Reward the player identified by the callback parameter.
  • Respond with HTTP 200 OK when successful.
Example: PHP Integration
<?php
$secret = "YOUR_SECRET_KEY"; // must match your toplist settings

if (!isset($_GET['secret']) || $_GET['secret'] !== $secret) {
    http_response_code(403);
    exit("Invalid secret");
}

$player = $_GET['callback'] ?? 'unknown';
$ip = $_GET['ip'] ?? 'unknown';

http_response_code(200);
echo "Vote registered for $player (IP: $ip)";
?>
Example: Node.js (Express)
import express from "express";
const app = express();

const CALLBACK_SECRET = "YOUR_SECRET_KEY";

app.get("/vote/callback", (req, res) => {
  const { callback, ip, secret } = req.query;

  if (secret !== CALLBACK_SECRET) {
    return res.status(403).send("Invalid secret");
  }

  console.log(`Vote received for ${callback} from IP ${ip}`);
  res.status(200).send("Vote registered successfully");
});

app.listen(3000, () => console.log("Callback listener running on port 3000"));
Example: Java (Spring Boot)
package com.example.vote;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VoteCallbackController {

    private static final String CALLBACK_SECRET = "YOUR_SECRET_KEY";

    @GetMapping("/vote/callback")
    public String handleVoteCallback(
            @RequestParam String callback,
            @RequestParam String ip,
            @RequestParam String secret
    ) {
        if (!CALLBACK_SECRET.equals(secret)) {
            return "Invalid secret";
        }

        System.out.println("Vote received for " + callback + " from IP " + ip);
        return "Vote registered successfully";
    }
}
Testing Your Integration
curl "https://yourdomain.com/vote/callback?callback=TestUser&ip=1.2.3.4&secret=YOUR_SECRET_KEY"
  • Always validate the secret key.
  • Use HTTPS for all callback URLs.
  • Log all incoming requests.
  • Respond with HTTP 200 to confirm success.
  • Use one callback endpoint per server.
List Your Server