Vote rewards

Voting Check

How you reward players after they successfully vote for your listing on JoinGameServers.

Open dashboard How it works

Setup path: Dashboard → Edit server → Vote Rewards (and Minecraft Details for Votifier).

01

How it works

  1. Player opens your vote link, ideally with ?p=USERNAME so the form is prefilled.

  2. They submit the vote. We enforce a 24-hour cooldown per IP (and per logged-in account). If rewards are configured, the username / parameter is required.

  3. We notify your rewards systems: HTTP GET to your postback URL and/or a Votifier packet to your Minecraft host — using the same parameter and the voter’s IP.

  4. You grant the reward. Delivery failures on your side are logged here but do not remove the vote.

Choose a method

HTTP Postback

Best for websites, launchers, and non-Minecraft games. For Minecraft this is an optional alternative to Votifier (or an addition if you also reward on a website).

  • Works for every game on this list
  • You control points, cooldowns, logging
  • Needs a public HTTPS endpoint
Postback PHP →
Best for Minecraft

Minecraft Votifier

Preferred for Minecraft. Best for in-game crates, keys, and listener plugins. We open a TCP connection to your Votifier port.

  • Minecraft listings only
  • Classic RSA or NuVotifier v2 token
  • Needs an open port + firewall allowlist
Minecraft Votifier →

For Minecraft, use Votifier first. HTTP postback is optional (or additional). Each enabled channel runs independently after the vote.

Quick start

  1. Log in and open Dashboard.
  2. Edit your approved server listing.
  3. Set a Postback URL and/or enable Votifier under Minecraft Details.
  4. Copy the incentive voting link from the edit form (ends with ?p=USERNAME).
  5. Place that link on your website or Discord; replace USERNAME per player.
  6. Cast a test vote and confirm rewards arrive.
02

Postback PHP

After a successful vote we request your URL with the player parameter and their IP. Your script marks that account as having voted and grants points or items.

Whitelist this website’s public outbound IP in your firewall and postback script. Reject every other source. Prefer HTTPS.

1. Set your Postback URL

Dashboard → Edit server → Vote Rewards → Postback URL.

https://YOURDOMAIN/postback.php
  • The filename is arbitrary — use any path your stack prefers.
  • Only public http/https URLs are accepted. Localhost, private LAN IPs, and URL credentials are rejected (SSRF protection).
  • We follow a small number of redirects and time out after a few seconds so voting stays fast.

2. Build incentive voting links

Append a parameter so each player is identified when they land on the vote page.

/GAME/server/SLUG/vote?p=PARAMETER
Piece Rules
PARAMETER / p_resp Letters, numbers, _, - only · max 32 characters · username, account id, or any id you track
ip IPv4 or IPv6 of the voter as seen by this list (proxy-aware when enabled)
Prefill query ?p= or ?username=

3. What we call after a vote

Only on success. If the player did not complete a valid vote, we send no request.

https://YOURDOMAIN/postback.php?p_resp=PARAMETER&ip=USERIP
Incentive link Our callback
/minecraft-server/server/your-server-slug/vote?p=1234 …/postback.php?p_resp=1234&ip=123.123.123.123
/minecraft-server/server/your-server-slug/vote?p=Razor …/postback.php?p_resp=Razor&ip=123.123.123.123

When we hit your postback with p_resp=Razor, player Razor has voted. The ip value is the address they used on this list.

What your script should do

  • Verify the request comes from this list’s public IP.
  • Sanitize p_resp and ip (never trust raw input).
  • Confirm the account / character exists in your database.
  • Apply your own reward cooldown if you need something stricter than 24 hours.
  • Grant points, coins, or items; log the event; return HTTP 200.

postback.php example

Host this on your rewards site, not necessarily on this vote list. Set VOTE_LIST_IP to this website’s outbound public IP before going live.

<?php
/**
 * Example vote postback receiver for YOUR game website / CMS.
 *
 * Configure this URL on your listing under Dashboard → Edit server → Vote Rewards.
 * This list will call it ONLY after a successful vote:
 *
 *   https://yoursite.com/postback.php?p_resp=PARAMETER&ip=USERIP
 *
 * PARAMETER is the username / account id the player entered on the vote form
 * (or the value from ?p= on your incentive voting link).
 *
 * Docs: /voting-check
 */

define('DEBUG', 0); // set to 1 to write _postback.log
define('LOG_FILE', __DIR__ . '/_postback.log');

/**
 * Only accept callbacks from the vote list's public IP.
 * Leave empty to skip the allowlist (not recommended in production).
 *
 * Example: define('VOTE_LIST_IP', '203.0.113.10');
 */
define('VOTE_LIST_IP', '');

$ipRequest = $_SERVER['HTTP_CF_CONNECTING_IP']
    ?? (isset($_SERVER['HTTP_X_FORWARDED_FOR'])
        ? trim(explode(',', (string) $_SERVER['HTTP_X_FORWARDED_FOR'])[0])
        : null)
    ?? $_SERVER['REMOTE_ADDR']
    ?? '';
$ipRequest = trim((string) $ipRequest);

if (VOTE_LIST_IP !== '' && $ipRequest !== VOTE_LIST_IP) {
    if (DEBUG) {
        error_log(date('[Y-m-d H:i] ') . "[Invalid] Request from {$ipRequest}" . PHP_EOL, 3, LOG_FILE);
    }
    http_response_code(403);
    exit('Forbidden');
}

if (DEBUG) {
    error_log(date('[Y-m-d H:i] ') . "[OK] Valid callback: {$ipRequest}" . PHP_EOL, 3, LOG_FILE);
}

// Clean parameters from the vote list (letters, numbers, underscore, hyphen).
$p = preg_replace('/[^A-Za-z0-9_\-]+/', '', (string) ($_GET['p_resp'] ?? '')) ?? '';
$userIp = preg_replace('/[^0-9a-fA-F:\.]+/', '', (string) ($_GET['ip'] ?? '')) ?? '';

if ($p === '') {
    http_response_code(400);
    exit('Missing p_resp');
}

if (DEBUG) {
    error_log(date('[Y-m-d H:i] ') . "[GET] Parameters [p_resp]={$p} [ip]={$userIp}" . PHP_EOL, 3, LOG_FILE);
}

// ---------------------------------------------------------------------------
// Connect to your database, verify account $p exists, enforce your own
// cooldown if needed, then grant vote points / items to $p (voted from $userIp).
// We send p_resp + ip ONLY when that player successfully voted on the list.
// ---------------------------------------------------------------------------

http_response_code(200);
echo 'OK';
03

Minecraft Votifier

We can push the vote straight into your Minecraft server. A listener plugin then runs your reward commands.

Firewall: allow inbound TCP from this website’s public IP to your Votifier port (default 8192). Do not expose the port to the whole internet if you can avoid it.

  1. Player enters their Minecraft username on our vote page (or arrives via ?p=Steve).

  2. Vote succeeds on this list.

  3. We connect to your Votifier host/port and deliver the vote packet.

  4. Your listener grants crates, keys, money, etc.

Enable Votifier under Minecraft Details, choose NuVotifier v2 or Classic, then enter host, port, and token or RSA public key.

Install NuVotifier (classic RSA and protocol v2) or classic Votifier, plus a listener for your Minecraft version (GAListener, SuperbVote, or a custom listener).

Classic / v1: paste the full public.key file. Host and port come from config.yml. Keep debug: true while connecting this list, then turn it off.

host: YOUR_PUBLIC_IP
port: 8192
debug: true

Packets identify this list as: JoinGameServers

04

NuVotifier v2

Protocol v2 replaces RSA with a shared token and a one-time challenge. Map a token to this list’s service name, or use the default token.

tokens:
  default: REPLACE_WITH_DEFAULT_TOKEN
  "JoinGameServers": REPLACE_WITH_LIST_TOKEN

Wire format: TCP connect → read greeting VOTIFIER 2 <challenge> → JSON payload (username, serviceName, timestamp ms, address, challenge) → Base64(HMAC-SHA256(payload, token)) → magic 0x733A + length + JSON {signature, payload}. Expect {"status":"ok"}.

Symptom Likely cause
Not a NuVotifier v2 server Greeting has no challenge — use Classic, or upgrade NuVotifier and enable v2.
Invalid signature / unknown service Wrong token, or service name not mapped. Add the list service name or use default.
Connect failed / timeout Bad host/port, Votifier offline, or firewall blocking this list’s IP.
No response Proxy/plugin interference; enable NuVotifier debug and retry.
05

Testing checklist

  1. Save listing settings without validation errors.
  2. Open an incentive link — the username field should prefill from ?p=.
  3. Cast one vote. You should see the success state. A second vote within 24 hours must be blocked.
  4. Verify postback: enable DEBUG in your receiver; confirm p_resp and ip arrive.
  5. Verify Votifier: with debug true, the Minecraft console should show an incoming vote for your username and this list’s service name.
  6. Confirm the in-game or site reward. If not, fix the listener — the list vote still counts.

Delivery attempts are recorded in vote_reward_logs (ok / fail / skipped). A failed callback never rolls back the vote on this list.

06

FAQ & troubleshooting

No. Guests can vote. Logged-in accounts share the same 24-hour cooldown rules for abuse prevention.

If you configured a postback URL or Votifier, we need a parameter to tell you who to reward. Without rewards configured, username stays optional.

Yes. Both run after a successful vote. Failures are independent.

It must be a public http(s) URL. Localhost, .local, private IPs (e.g. 10.*, 192.168.*), and URLs with embedded credentials are blocked.

Confirm the vote succeeded on this list. Check your postback logs or NuVotifier debug output. Verify firewall allowlists and that the username matches an in-game account. List cooldown is 24 hours; your own reward cooldown can differ.

Only A–Z, a–z, 0–9, _, and -. Anything else is stripped. Keep parameters ≤ 32 characters.