Vote Rewards Integration Guide

Vote Rewards lets your players earn in-game rewards for voting for your server on Nostalgic.gg. The callback contract is gtop100-compatible — if you already run a gtop100 receiver script, you only need to swap the URL and secret.

What is Vote Rewards

When a player votes for your server, Nostalgic.gg records the vote and queues a reward event. A background worker then POSTs that event to a callback URL you control. Your script validates the request and grants whatever in-game reward you choose.

Votes run on a rolling 12-hour cycle — each player can vote once per server per cycle. Rewards are entirely yours to define: coins, items, buffs, anything your server supports.

How it works

A player votes for your server on Nostalgic.gg.
Nostalgic queues a reward event for that vote.
A cron worker POSTs the event (batched, up to 50 at a time) to your callback URL.
Your script validates siteid + pingbackkey, then grants the reward.
Your script responds HTTP 200 and Nostalgic marks the reward delivered.

Callback payload

Nostalgic sends a JSON POST in the gtop100 pingback format:

POST <your-callback-url>
Content-Type: application/json

{
  "siteid": "12345",
  "pingbackkey": "<your-secret-from-the-dashboard>",
  "Common": [
    {
      "pb_id": 87654321,
      "ip": "a1b2c3d4e5f6",
      "success": 0,
      "reason": "OK",
      "pb_name": "DragonSlayer99"
    }
    /* up to 50 events batched per POST */
  ]
}

Field	Meaning
siteid	Your Nostalgic.gg server id (as a string). Verify it matches your server.
pingbackkey	Your callback secret. Compare it against the secret from your dashboard before granting anything.
Common[]	Array of vote events — up to 50 batched per POST.
pb_id	Unique vote id. Use it as the idempotency / dedupe key so retries never double-reward.
ip	Truncated, hashed IP fragment — not a real IP. Informational only.
success	0 means the vote counted (gtop100 convention).
reason	Human-readable status, e.g. "OK" or "TEST".
pb_name	The player's in-game username — the account to grant the reward to.

Sample PHP receiver

A minimal, copy-paste receiver. Replace the two placeholders with the values from your Nostalgic.gg dashboard, then implement your own reward logic where marked.

<?php
// vote-reward-callback.php — drop this on your server, set the URL in your
// Nostalgic.gg dashboard (Vote Rewards → Callback URL).
$expectedSecret = 'YOUR_SECRET_FROM_NOSTALGIC';
$expectedSiteId = 'YOUR_SERVER_ID_FROM_NOSTALGIC';

$body = json_decode(file_get_contents('php://input'), true);
if (!$body || $body['siteid'] !== $expectedSiteId || $body['pingbackkey'] !== $expectedSecret) {
  http_response_code(403);
  exit('Invalid');
}

foreach ($body['Common'] as $vote) {
  $pbId = (int)$vote['pb_id'];
  $playerName = $vote['pb_name'];

  // pb_id 999999999 is the dashboard "Test webhook" event — never reward it.
  if ($pbId === 999999999) { continue; }

  // TODO: check if $pbId was already credited (dedupe), then grant the reward.
  // Example placeholder:
  // file_put_contents('voted-' . $playerName . '.txt', $pbId, FILE_APPEND);
}

http_response_code(200);
echo 'OK';

Setup checklist

Choose a public HTTPS URL on your server for the callback.
Create a receiver script there (use the PHP sample above as a starting point).
In your Nostalgic.gg dashboard, open Vote Rewards, set the callback URL and Save — you receive a secret (shown once).
Paste that secret into your script, then use Test webhook to confirm it responds 200.
Set delivery mode to Push and tick Enabled.

Retry behavior

If your callback returns a non-2xx status or times out (10s), Nostalgic retries with a 1-minute, then 5-minute, then 30-minute backoff — up to 3 attempts before the event is marked failed. Because pb_id is stable across retries, always dedupe on it so a retried delivery never grants the reward twice.

Security FAQ

Why a plaintext secret instead of HMAC? The gtop100 contract sends the secret as pingbackkey in the body and receiver scripts compare it directly — this keeps Nostalgic drop-in compatible with existing gtop100 scripts. Keep your callback URL on HTTPS so the secret is never sent in cleartext.

What if my secret leaks? Use Regenerate Secret in the dashboard, then update your script. The old secret stops validating immediately.

Troubleshooting

403 from your script — siteid or pingbackkey doesn't match. Re-copy the secret.
Timeout — your script took longer than 10s. Grant rewards asynchronously and respond 200 fast.
Nothing arrives — confirm delivery mode is Push, Enabled is ticked, and the URL is publicly reachable.
Watch the Recent Deliveries table in your dashboard for per-event status and errors.

Embed the vote widget

Add a vote button to your own website. The widget shows your live vote count and links straight to your Nostalgic.gg page — and the backlink passes SEO equity that lifts your ranking here. Replace YOUR_SERVER_ID with your id:

<iframe src="https://nostalgic.gg/api/widgets/vote/YOUR_SERVER_ID"
        width="200" height="80" frameborder="0" scrolling="no"
        title="Vote on Nostalgic.gg"></iframe>