Skip to content
Tutorials

Callback documentation

By

What is incentive voting?

By default, the RULOCUS lists are ordered by vote count. The more votes a server has, the higher it will rank. To keep your players motivated to vote for your server, you will most likely need to reward them for their votes. This is what we use to call “incentive voting”.

Loading ad...

How does incentive voting work?

The idea of incentive voting is quite simple. You send your players to a unique voting URL, the players vote and then we notify your system to let you know the player has successfully voted. It’s up to you to decide what you’re going to do next. How are you going to reward your player?

How can you install incentive voting?

1. Setting a Callback URL and Secret

The first step is providing us with a so-called “Callback URL”. This is a hidden page on your website which we will load (“call”) once a player has voted. You can provide your Callback URL in your server settings.

Additionally, you should set a Callback Secret – a unique key that we’ll send back with each callback to verify the request is legitimate. This protects you from potential abuse where someone might try to fake votes by calling your callback URL directly.

Note: Using Cloudflare? We recommend disabling it on your callback URL, as it might block the callback.

2. Send your players to your voting page at RULOCUS

While this step might seem straightforward, you do need to pay close attention. You’ll want to make sure the voting page URL has the right formatting, a correct example is:

https://www.rulocus.com/top-rsps-list/yourserver/vote?callback=CONTENTHERE

In the example above, the base URL is bold. You can find your server’s base URL in your account – it depends on your server name, as well as the gaming category your game is listed in.

We completed the base URL with “/vote?callback=CONTENTHERE“, you’ll need to do the same. The “CONTENTHERE” in our example can be anything unique of your choice, to help you identify your player (e.g. player name, session ID, IP address, etc). We will pass this back to your Callback URL after a successful vote.

3. Processing successful votes on your system

For this example, we will use the following callback URL: https://www.yourdomain.com/voteprocessing

We send the following variables to your callback URL (using both $_POST and $_GET):

  • callback – the aforementioned URL parameter (in our example “CONTENTHERE”).
  • ip – the voter’s IP address (might be useful for some servers).
  • secret – your callback secret key (if configured) for verification.

The final callback URL we would call is:
https://www.yourdomain.com/voteprocessing?callback=CONTENTHERE&ip=VOTERIP&secret=YOURSECRET

How you’re going to process these variables is completely up to you. Below is a quick PHP snippet you can place on your callback page to log votes in a MySQL table, or use it as a starting point for your own script:

4. Security Best Practices

  • Always use a callback secret: Generate a strong, unique secret key (at least 32 characters) and keep it private.
  • Use HTTPS: Ensure your callback URL uses HTTPS to prevent interception.
  • Implement rate limiting: Track IPs and prevent abuse by limiting votes per IP address.
  • Log attempts: Keep logs of both successful and failed callback attempts for security monitoring.
  • Return appropriate HTTP status codes: Use 200 for success, 403 for invalid requests, and 429 for rate limiting.

5. Testing the callback

Have you finished setting up the callback and the rest of the incentive voting process? Use our Callback Tester to verify everything works. The tester will send a test callback with your configured secret to ensure your endpoint is working correctly.

Loading ad...