Callback Documentation

Callbacks are how our toplist tells your server that a player has successfully voted. By validating the request and rewarding the player automatically, you can ensure secure and instant reward delivery for every legitimate vote, improving engagement and trust within your community.

List Your Server

Create your listing with clear tags, a strong banner, and a secure callback identifier to track votes.

Set Up Callback

Configure your callback URL and secret to reward players automatically after successful votes.

Climb The Toplist

Boost voting, grow engagement, and strengthen your community on the rsps toplist.

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