Developer guide

Vote callback reference

When a player votes for your server, we tell your server by opening a web address you choose, with the player's name on the end. Your script gives the reward and says “OK”. That is the whole thing; this page covers the details.

We send1 GET requestno body, no JSON

Success meansHTTP 200the body is ignored

Answer within3 secondsor it counts as failed

If it fails5 retriesafter 30 s, 2 min, 10 min, then about 1 h and 6 h

Player opens your vote link…/server/293/vote/Zezima — the last part is the player's name.

They solve the captchaand press Vote Now.

We call your callback URLwith the name attached: one GET request.

Your script rewards the playerand answers with status 200.

The request we send

The part after /vote/ in the vote link is called the incentive. It is normally the player's in-game name, but it can be anything your server understands, such as an account id or a one-time token. We add it to the end of the callback URL you saved. How we add it depends only on how your saved URL ends:

Ends with =the most flexible

You savehttps://play.example/vote?user=

We callhttps://play.example/vote?user=Zezima

Ends with .phpclassic vote scripts

You savehttps://play.example/callback.php

We callhttps://play.example/callback.php?postback=Zezima

Anything elsename in the path

You savehttps://play.example/api/vote

We callhttps://play.example/api/vote/Zezima

With the first shape you can put your own parameters in front, for example a secret key: https://play.example/vote?key=YOUR_SECRET&user=

On the wire it looks like this (plus the usual connection headers):

GET /vote?user=Zezima HTTP/1.1
Host: play.example
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36
Accept: text/html,application/xhtml+xml,…
Accept-Language: en-US,en;q=0.9
X-RuneList-Vote-Id: 48211907
X-RuneList-Attempt: 1
X-RuneList-Timestamp: 1790000000
X-RuneList-Voter-Ip: 203.0.113.42
X-RuneList-Voter-Country: GB

Always GET. Nothing is sent in a request body. A signature header is added only if you turn on signed callbacks.
Extra headers carry what the URL cannot. X-RuneList-Vote-Id is the same on every retry of one vote, X-RuneList-Attempt counts the tries, and X-RuneList-Timestamp is when we sent it (Unix seconds). You can ignore them; if you store the vote id you can skip a vote you already rewarded.
X-RuneList-Voter-Ip is the address the vote came from (IPv4 or IPv6) and X-RuneList-Voter-Country its two-letter country code, empty when we do not know it. Use them to spot the same person voting through many proxies, to give a reward only once per address, or to keep a region out of a promotion. They are in headers, not in the URL, so a script written for the old site keeps working unchanged. Read them with $_SERVER['HTTP_X_RUNELIST_VOTER_IP'] in PHP, req.headers['x-runelist-voter-ip'] in Node. Treat the address as personal data: keep it only as long as your reward rule needs it.
Both https:// and http:// work, and up to 5 redirects are followed. Use https when you can. The address has to be public: we do not call localhost, private network addresses or machine names without a domain.
We identify as a normal web browser, because many hosts block unknown clients. Do not use the User-Agent or our IP address to recognise us; both can change.
The incentive is added exactly as it appears in the vote link, up to 255 characters. We do not clean or escape it: a space reaches you as a space, and characters such as &, # or ? in a name would change the URL. Always check the value before you use it.

What your script should answer

Answer with status 200 once the reward is stored. Any 2xx status counts as delivered; redirects that lead nowhere, 4xx and 5xx count as failed.
The response body does not matter. Keep it short (ok is perfect): we save the first 500 characters in your callback log so you can debug.
You have 3 seconds. A slower answer, a connection error or any other status counts as failed.
After a failure we try again 5 more times: after 30 s, then 2 min, then 10 min, and then about 1 hour and 6 hours after the vote, so a restart or a short outage does not lose the reward. After the last one we stop.
If nothing gets through for an hour while players keep voting, we email the server's owner once. While your address keeps failing we check it every 10 minutes instead of on every vote, and deliver the waiting rewards as soon as it answers.

You can receive the same vote twice. If your script stores the reward but answers too slowly, we think it failed and call again. Answer fast, and make rewards safe to repeat, for example at most one reward per player every 12 hours.

Player names with spaces

A web address cannot contain a real space, so a name like Iron Man has to be written in a way that survives the trip. You have two good options. Pick one and use it everywhere.

Option	Vote link you give the player	What we call	What your script reads
%20 (the standard way)	`…/vote/Iron%20Man`	`…?user=Iron%20Man`	`Iron Man` — PHP, Express, Flask, ASP.NET, Go and Sinatra decode it for you
Underscore (the RSPS habit)	`…/vote/Iron_Man`	`…?user=Iron_Man`	`Iron_Man` — turn `_` into a space yourself before you look the player up

Build the link with your language's URL encoder instead of by hand: rawurlencode() in PHP, encodeURIComponent() in JavaScript, urllib.parse.quote() in Python, Uri.EscapeDataString() in C#, url.PathEscape() in Go.
Java: URLEncoder.encode(name, UTF_8) writes a space as +, and in this part of a link a plus stays a plus, so the player would be called Iron+Man. Add .replace("+", "%20").
If you read the raw query string yourself (as the Java example does), decode it; the example's URLDecoder.decode line does exactly that.
A player who types a plain space into the address bar is fine too: the browser turns it into %20 on its own.
Names are passed on exactly as written, including upper and lower case. If your game treats iron man, Iron Man and Iron_Man as the same player, normalise the name in your script before you store the reward. The name check in the examples already allows spaces, _ and -.

When we call you, and when we don't

We call your URL

For every vote that passes the captcha and has a name in the link.
Also when the vote does not count towards your rank because the same device voted before or a VPN was detected. The player did the work, so they still get the reward.

We do not call

When the same IP address already voted for you in the last 12 hours.
When the vote link has no name (…/vote/ with nothing after it).
When one connection sends far too many votes in a few minutes.

Code examples

Every example does the same four things: check the secret key, check that the name looks like a real player name, store the reward, answer 200. Pick your language, change the name rule and the “your own code” line to fit your game.

Callback URL to save: https://play.example/callback.php

<?php
// callback.php
$player = $_GET['postback'] ?? '';

// 1. Only accept names your game could really have.
if (!preg_match('/^[A-Za-z0-9 _-]{1,12}$/', $player)) {
    http_response_code(400);
    exit('bad name');
}

// 2. Store the reward (your own table; the player claims it in game).
$db = new PDO('mysql:host=localhost;dbname=game;charset=utf8mb4', 'user', 'password');
$stmt = $db->prepare(
    'INSERT INTO vote_rewards (player, site, created_at) VALUES (?, ?, NOW())'
);
$stmt->execute([$player, 'runelist']);

// 3. Tell us it worked. Anything other than 200 is retried.
http_response_code(200);
echo 'ok';

Ends in .php, so the name arrives as ?postback=. To use a secret key with PHP, save https://play.example/callback.php?key=YOUR_SECRET&user= instead and read $_GET['user'].