Vote callback (postback)

For game owners. Last updated 13 November 2026.

When a player votes for your game after arriving through your vote link, TopLinks calls one URL on your server. That call is the postback. It tells your game who voted, so you can reward that player in your own game instead of guessing from an IP address.

This page documents exactly what we send, how to verify it, what to send back and how to test it. Every parameter below comes from the code that builds the call.

1. Set the URL and the secret

  1. Sign in and open your account.
  2. Click Edit next to your game.
  3. In the Vote postback card, fill in Postback URL, for example https://yourgame.com/vote-callback, and save.
  4. Leave Secret empty the first time. We generate a random one (32 hex characters) and store it with your listing. The field shows it after saving and stays editable, so you can rotate it later.

One listing has one URL and one secret. Do you own several games? Give each its own endpoint; the game parameter tells them apart.

2. When we call it

  • After a vote is counted. A vote that is refused (already voted today, daily maximum reached) never triggers a call.
  • Only when the visitor arrived through your vote link, that is /game/<slug>?ref=<your-user-id>, and that id is the owner of this listing. Without a ref, or with someone else's, we do not call anything.
  • Once per counted vote. We make one attempt: no retry, no queue.
  • With a timeout of 3 seconds (2 seconds to connect), following at most 2 redirects, with user agent TopLinks postback.
  • A slow or broken endpoint never blocks the vote. The player sees "Your vote is counted" either way.

3. The parameters we send

The call is a plain HTTP GET, with the parameters below. We append them to your URL with ? or & when your URL already has a query string.

ParameterTypeWhat it means
useridinteger, always Your TopLinks account id. This is the ref from your vote link, and we only call when it is the owner of the listing. Use it to find your own row and the matching secret.
gameinteger, always The TopLinks id of your listing (the number in /account/listing/<id>). Handy when one endpoint serves several of your games.
playerinteger, always TopLinks id of the person who voted, 0 when they were not signed in. This is a voter on our site, not a player in your game. Do not reward on this value.
ipstring, always The address the vote came from, as our server received it: IPv4 or IPv6, not hashed. For an abuse check only. Do not publish it and do not keep it longer than you need.
tsinteger, always Unix timestamp in seconds, set when we make the call. Reject old values, see section 4.
uidinteger, optional The player's id in your game, taken from the vote link (&uid=1234, we also accept &userid=1234 there). Present only when the link carried it. This is the id you reward.
sigstring, optional HMAC-SHA256 over the parameters, as 64 hex characters. Only present when a secret is set on the listing.
tsigstring, optional Second signature over <uid>|<ts>. Only when uid is present and a secret is set.
testinteger, optional 1 for a call from the test button. Never in a real vote. A test call has no uid and no tsig.

A real call looks like this (line breaks added for reading, the actual call is one line):

GET https://yourgame.com/vote-callback?userid=42&game=17&player=0&ip=203.0.113.9&ts=1792339000&uid=7654&sig=9f2c...&tsig=4a71...

4. The signature

When your listing has a secret, we sign the call. Two values, both HMAC-SHA256 with that secret:

sig  = HMAC-SHA256( http_build_query([userid, game, player, ip, ts, (uid)]) , secret )
tsig = HMAC-SHA256( uid . "|" . ts , secret )

The key order above is part of the signature, and so is the URL encoding. Rebuild the string yourself from the values you received, in that order, then compare. Do not sign the raw query string of the request: your web server may reorder or re-encode it.

tsig is not covered by sig. Verify both when both are present, with a constant time compare (hash_equals in PHP).

A test call carries test=1 after ts, and that field is signed too. So the string you verify for a test call is userid, game, player, ip, ts, test, without uid.

Reject a call when ts is more than a few minutes old. We suggest 300 seconds. Without that check an old URL, sig included, stays valid forever.

5. What we expect back

  • An HTTP 2xx status and a short body, for example ok. Anything else counts as failed in your dashboard.
  • Answer 200 for calls you handled and for calls you deliberately ignore (unknown player, test call). Use 4xx only for a real problem you want to see flagged: a bad signature or an unknown listing.
  • Answer within a second where you can. We wait 3 seconds; if you need longer, store the vote and reward it from your own queue, then answer 200.

We log every call in our postbacks table: the listing, the date, the URL (up to 500 characters), the HTTP status code and the first 300 characters of your answer.

  • On /account a listing with a callback shows "postback set (last HTTP 200)", or whatever your last status code was. HTTP 0 means we got no answer at all: timeout, DNS, a refused connection or a TLS error.
  • On the edit page, Verify votes lists the ten most recent calls with their date and HTTP code. Anything outside 2xx is marked failed.
  • We do not retry. One call per vote, one line in that log.

6. Complete PHP example

A single file you can drop next to your game. It verifies the call, looks up the player, rewards once per day and answers 200.

<?php
declare(strict_types=1);

/**
 * vote-callback.php: receives TopLinks vote postbacks.
 * Put this file next to your game and use its URL as the Postback URL.
 *
 * 1. read the call  2. check ts  3. verify sig/tsig  4. reward once  5. answer 200
 */

const POSTBACK_SECRET = 'paste the secret from your listing here';
const MAX_AGE = 300;            // seconds between our call and your clock
const REWARD_GOLD = 10;

header('Content-Type: text/plain; charset=utf-8');

function answer(int $code, string $text): never
{
    http_response_code($code);
    echo $text;
    exit;
}

$pdo = new PDO('mysql:host=127.0.0.1;dbname=yourgame;charset=utf8mb4', 'dbuser', 'dbpass', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

$game   = (int) ($_GET['game'] ?? 0);
$ts     = (int) ($_GET['ts'] ?? 0);
$uid    = (int) ($_GET['uid'] ?? 0);
$isTest = (int) ($_GET['test'] ?? 0) === 1;

if ($game <= 0 || $ts <= 0) {
    answer(400, 'missing game or ts');
}
if (abs(time() - $ts) > MAX_AGE) {
    answer(400, 'stale ts');
}

/* Rebuild what we signed: same keys, same order, sig and tsig left out. */
$params = [
    'userid' => (int) ($_GET['userid'] ?? 0),
    'game'   => $game,
    'player' => (int) ($_GET['player'] ?? 0),
    'ip'     => (string) ($_GET['ip'] ?? ''),
    'ts'     => $ts,
];
if ($uid > 0) {
    $params['uid'] = $uid;
}
if (isset($_GET['test'])) {
    $params['test'] = 1;        // a test call signs test=1 as well
}

$sig = hash_hmac('sha256', http_build_query($params), POSTBACK_SECRET);
if (!hash_equals($sig, (string) ($_GET['sig'] ?? ''))) {
    answer(403, 'bad signature');
}

/* The uid has its own signature, over "<uid>|<ts>". */
if ($uid > 0 && !hash_equals(
    hash_hmac('sha256', $uid . '|' . $ts, POSTBACK_SECRET),
    (string) ($_GET['tsig'] ?? '')
)) {
    answer(403, 'bad tsig');
}

if ($isTest) {
    answer(200, 'test ok');         // wiring works, no reward
}
if ($uid <= 0) {
    answer(200, 'no uid, nothing to reward');
}

/* Your own player, found by the id from the vote link. */
$st = $pdo->prepare('SELECT id FROM players WHERE id = ? LIMIT 1');
$st->execute([$uid]);
if (!$st->fetchColumn()) {
    answer(200, 'unknown player');  // the call was fine, the player is not yours
}

/* One reward per player per day: the unique key absorbs a repeated call. */
$day = (new DateTimeImmutable('now', new DateTimeZone('Europe/Brussels')))->format('Y-m-d');
try {
    $pdo->beginTransaction();
    $pdo->prepare('INSERT INTO rewards (player_id, source, day, amount) VALUES (?, ?, ?, ?)')
        ->execute([$uid, 'toplinks', $day, REWARD_GOLD]);
    $pdo->prepare('UPDATE players SET gold = gold + ? WHERE id = ?')
        ->execute([REWARD_GOLD, $uid]);
    $pdo->commit();
} catch (PDOException $e) {
    if ($pdo->inTransaction()) {
        $pdo->rollBack();
    }
    if ((int) ($e->errorInfo[1] ?? 0) === 1062) {
        answer(200, 'already rewarded today');
    }
    answer(500, 'reward failed');
}

answer(200, 'ok');

7. Test it with curl

Sign a call yourself and send it. Handy while building the endpoint, before your game is live on the list.

# 1. The secret of your listing (Edit, then Vote postback, then Secret).
SECRET='the-secret-from-your-listing'

# 2. The query in the order we sign it.
TS=$(date +%s)
QUERY="userid=42&game=17&player=0&ip=203.0.113.9&ts=${TS}"

# 3. Sign it and call your endpoint.
SIG=$(php -r 'echo hash_hmac("sha256", $argv[1], $argv[2]);' "$QUERY" "$SECRET")
curl -i "https://yourgame.com/vote-callback?${QUERY}&sig=${SIG}"

# With a player id there is a second signature over "<uid>|<ts>":
UID=7654
QUERY="userid=42&game=17&player=0&ip=203.0.113.9&ts=${TS}&uid=${UID}"
SIG=$(php -r 'echo hash_hmac("sha256", $argv[1], $argv[2]);' "$QUERY" "$SECRET")
TSIG=$(php -r 'echo hash_hmac("sha256", $argv[1]."|".$argv[2], $argv[3]);' "$UID" "$TS" "$SECRET")
curl -i "https://yourgame.com/vote-callback?${QUERY}&sig=${SIG}&tsig=${TSIG}"

The answer is what our log stores, so a 200 with ok is exactly what you want to see.

8. Test with the button in your dashboard

  1. Open /account and click Edit next to the game.
  2. Fill in the Postback URL, save, and open the edit page again.
  3. In the Verify votes card, click Send test postback.
  4. The page reloads with a message: Test postback sent: HTTP 200 in green, or the real code in red when something is wrong.
  5. The attempt is stored like a real call, so it appears in the list under Verify votes and becomes the "last HTTP" code on /account.

The test call is a normal GET with userid, game, player=0, ip, ts, test=1 and sig. It has a 5 second timeout and no uid or tsig. Detect test=1, verify the signature, log it, answer 200 and do not hand out a reward. An endpoint that insists on a real player id will fail the test even though it works for real votes.

Do you see HTTP 403 on the test? Then the signature check fails. The usual causes: the secret in your code differs from the one in the listing, or you built the string without test=1.

9. Rules that keep it correct

  • Reward once. A call can arrive more than once: your own retry, a player replaying a URL within the time window, or a second vote on another device that our own check let through. Give the reward one unique key, for example UNIQUE (player_id, source, day) on your rewards table, and treat a duplicate insert as success.
    CREATE TABLE rewards (
      id        INT AUTO_INCREMENT PRIMARY KEY,
      player_id INT NOT NULL,
      source    VARCHAR(20) NOT NULL,      -- 'toplinks'
      day       DATE NOT NULL,             -- our vote day runs on Europe/Brussels
      amount    INT NOT NULL,
      created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
      UNIQUE KEY uniq_reward (player_id, source, day)
    );
  • No secrets in the URL. The secret itself never travels. Only the HMAC does. Do not add your own secret or API key to the postback URL either: we store the URL of recent calls, and so will your own web server logs. Rotate the secret in the listing when it may have leaked; calls signed with the old one stop verifying at once.
  • The IP is a raw address, not a hash. We send the voting connection's address so you can spot abuse. Do not put it in a public page, do not use it to identify a player when uid is there, and do not keep it longer than your abuse window.
  • Reward on uid, never on player. Build your vote link as https://toplinks.rocks/game/<slug>?ref=<your-id>&uid=<their-id>. If your link already has a ?, append with &.
  • Do not require player or uid. Anonymous votes have player=0 and test calls have no uid. Answer 200 and skip the reward instead of failing.
  • Use HTTPS. We follow redirects, but a redirect from http to https costs time inside a 3 second budget.
  • Compare in constant time. hash_equals, not ==.

Questions

Something in the call does not match what your server receives? Send us the date and the HTTP code from Verify votes through the contact form, and we look it up in our log.