Vote rewards in 3 steps
Rewarding the people who vote for your game is what brings your community back to vote every day. On IdleHub it is a webhook: on every vote, IdleHub notifies your game server right away, with a signature, and the game hands out the prize on its own. No anti-multi-account logic on your side — IdleHub already hands out 1 reward per nickname every 24 h, no matter how many accounts vote for the same nickname.
- Submit your game and, once it is approved, open My games → Vote reward. Turn on the reward with your webhook URL and copy the key (it stays on your game server only).
- Add the vote button to your game, with the nickname of whoever clicked it:
https://idlehub.io/votar/YOUR-GAME?jogador=NICK - Receive the notice: a route on your game server checks the signature and gives out 1 prize per vote. Your coding AI builds this part with the prompt right below.
Build it with AI
With AI: copy and paste
Paste it into Claude Code, Cursor, Copilot or whatever coding AI you use, opened in your game server folder: it reads your code and builds the webhook route, the vote button and the test. In your game dashboard, the same prompt comes with your game name and URL already filled in.
Show the prompt
Implement the IdleHub vote reward on the server of my game.
What it is: IdleHub (https://idlehub.io) is a ranking of idle games. When someone votes for my game there, IdleHub immediately sends a signed notice (webhook) to the game server, and the game gives 1 prize to the nickname in the notice. IdleHub handles the fraud: each nickname gets at most 1 reward every 24 h, no matter how many accounts vote for it. So it is always: 1 notice = 1 prize.
Before writing any code, read the project and find out: the server language and framework, where the HTTP routes live, the database, how to find a player by nickname and how to give them an item or currency.
PRIZE PER VOTE: [write it here, e.g. 100 coins]. If this is still in brackets, ask me what the prize is before implementing.
1. The webhook route
- POST /idlehub (or another path that fits the project). It must be public over HTTPS, on port 443, on the game's domain or one of its subdomains.
- Read the RAW body (the exact bytes, up to 64 KB) before any JSON parser: the signature is computed over those bytes.
- Headers:
X-IdleHub-Evento: the notice's unique id (the same value comes in Idempotency-Key)
X-IdleHub-Momento: when it was sent, in Unix seconds
X-IdleHub-Assinatura: sha256=<hex>, the HMAC-SHA256 of "<momento>.<raw body>" with the game key
- Check the timestamp (at most 300 s away from the server clock) and the signature, comparing in constant time (timingSafeEqual, hash_equals, hmac.compare_digest...). If it fails, answer 401 and do nothing else.
- The key comes from the IDLEHUB_CHAVE environment variable: "ih_" plus 40 letters and digits. If it is missing, empty or in any other format, the server refuses to start (or the route answers 500): never check the signature with an empty key. Never write it in the code, in logs or in the repository.
- The body is JSON: {"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"your-game","jogador":"Nick","votadoEm":"2026-11-16T14:32:07.000Z","proximoVotoEm":"2026-11-17T14:32:07.000Z","teste":false}
- "tipo": "verificacao" is the URL challenge: it comes with the first "Send test" in the dashboard (and again after the URL or the key changes), as {"tipo":"verificacao","desafio":"vrf_...","teste":true}. Handle it BEFORE anything else, after checking the signature: answer 200 with the JSON {"resposta": "<HMAC-SHA256 of the text "verificacao." + desafio, with the key, in hex>"} and do NOT give a prize. Without this answer, IdleHub sends no test and no vote to the route.
- "teste": true (with "tipo": "teste") is the "Send test" button in the IdleHub dashboard: answer 200 and do NOT give a prize.
- Store every paid "evento" in a table with a unique key. The same notice can arrive again if the response gets lost: repeated event = answer 409 and don't pay again.
- Find the player by nickname the way the game already looks players up (the nickname comes exactly as the person typed it). Not found = answer 404: the voter sees it and can fix the nickname, and the notice comes back with the SAME event.
- Give the prize and save the event as paid in the SAME transaction. Then answer 200.
- Answer within 5 seconds, without redirecting.
- For IdleHub: 2xx or 409 = delivered; 400, 404, 410 or 422 = nickname rejected; 401, 403, 405 or 501 = configuration error (it stops and shows it in the dashboard, with a resend button); 429, 5xx or too slow = it retries after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h.
- If the server sits behind Cloudflare or another firewall that blocks bots, allow POST on this route: the caller is a server, with no browser.
2. The vote button
- In the game UI, a "Vote on IdleHub" button that opens in a new tab:
https://idlehub.io/votar/your-game?jogador=<the logged-in player's nickname, URL-encoded>
- Send only the nickname: never a password, token or email.
3. (Optional) "Vote again in X h" inside the game
- From the game SERVER, never from the browser: GET https://idlehub.io/api/v1/status?jogador=<nickname> with the header Authorization: Bearer <IDLEHUB_CHAVE>. The response has "podeGanharDeNovo" and "proximaRecompensaEm".
When you are done, tell me: the files you changed, the full route URL for me to register in the IdleHub dashboard, where to put IDLEHUB_CHAVE and how to test it with the dashboard's "Send test" button.
Full guide: https://idlehub.io/desenvolvedores
The webhook
In the dashboard, register a URL that is HTTPS, on port 443, on your game's domain (or one of its subdomains). For every vote, IdleHub sends:
POST https://api.yourgame.com/idlehub
Content-Type: application/json
X-IdleHub-Evento: evt_8Kd2mQ1xTn9rAb3cDe
Idempotency-Key: evt_8Kd2mQ1xTn9rAb3cDe
X-IdleHub-Momento: 1763217127
X-IdleHub-Assinatura: sha256=<HMAC-SHA256 of "momento.corpo" with your key>
{"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"your-game","jogador":"Nick",
"votadoEm":"2026-11-15T14:32:07.000Z","proximoVotoEm":"2026-11-16T14:32:07.000Z","teste":false}
"tipo": "verificacao"is the URL challenge: it comes with the first Send test and again after you change the URL or the key. Answer 200 with{"resposta": "…"}: the HMAC-SHA256 ofverificacao.+desafiowith your key, in hex (the examples below already do it). Without this proof, IdleHub sends no test and no vote to the URL."teste": true(with"tipo": "teste") is the Send test button in the dashboard: answer 2xx and give no prize.- For the "1 reward per nickname" rule, nicknames are compared like an accent- and case-insensitive search: case, accents, character width, invisible characters and letters such as ø, ł and æ do not count — "Fasi", "fasí", "FASI" and "Bjørn"/"Bjorn" are the same nickname. Your game receives the nickname exactly as it was typed.
| Your response | What IdleHub does |
|---|---|
| 2xx | Marks it as delivered. |
| 409 | "Already processed": also counts as delivered. |
| 400, 404, 410, 422 | Player rejected: the voter sees a notice and can fix the nickname within 24 h (the notice comes back with the SAME evento). |
| 401, 403, 405, 501 | Stops right away (it is a setup problem): it shows up in the dashboard, with a resend button. |
| 429, 5xx, timeout | Retries after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. |
Reply within 5 seconds. IdleHub does not follow redirects. Since the same notice can arrive more than once, store every evento you have already paid.
Node.js
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const CHAVE = process.env.IDLEHUB_CHAVE ?? '';
if (!/^ih_[0-9A-Za-z]{40}$/.test(CHAVE)) throw new Error('IDLEHUB_CHAVE missing or invalid');
// Keep the RAW body (in Express: express.raw({ type: 'application/json' })).
function avisoDoIdleHubValido(corpoCru, cabecalhos, chave) {
const momento = cabecalhos['x-idlehub-momento'];
if (!momento || Math.abs(Date.now() / 1000 - Number(momento)) > 300) return false;
const esperada = Buffer.from('sha256=' + crypto.createHmac('sha256', chave)
.update(`${momento}.${corpoCru}`).digest('hex'));
const recebida = Buffer.from(String(cabecalhos['x-idlehub-assinatura'] || ''));
return recebida.length === esperada.length && crypto.timingSafeEqual(recebida, esperada);
}
app.post('/idlehub', express.raw({ type: 'application/json', limit: '64kb' }), (req, res) => {
if (!avisoDoIdleHubValido(req.body, req.headers, CHAVE)) return res.sendStatus(401);
const aviso = JSON.parse(req.body);
if (aviso.tipo === 'verificacao') { // URL challenge: proof that the route has the key
return res.json({ resposta: crypto.createHmac('sha256', CHAVE).update('verificacao.' + aviso.desafio).digest('hex') });
}
if (aviso.teste) return res.sendStatus(200); // dashboard test: do not pay
if (jaPago(aviso.evento)) return res.sendStatus(409); // already delivered
if (!jogadorExiste(aviso.jogador)) return res.sendStatus(404); // the voter fixes the nickname
// the two lines below in the SAME database transaction
darPremio(aviso.jogador, 1);
marcarPago(aviso.evento);
res.sendStatus(200);
});
PHP
<?php
$cru = file_get_contents('php://input');
$momento = $_SERVER['HTTP_X_IDLEHUB_MOMENTO'] ?? '';
$recebida = $_SERVER['HTTP_X_IDLEHUB_ASSINATURA'] ?? '';
$chave = getenv('IDLEHUB_CHAVE'); // IDLEHUB_CHAVE missing or invalid: 500 (o IdleHub tenta de novo)
if (!is_string($chave) || !preg_match('/^ih_[0-9A-Za-z]{40}z/', $chave)) { http_response_code(500); exit; }
if (!ctype_digit($momento) || abs(time() - (int) $momento) > 300) { http_response_code(401); exit; }
$esperada = 'sha256=' . hash_hmac('sha256', $momento . '.' . $cru, $chave);
if (!hash_equals($esperada, $recebida)) { http_response_code(401); exit; }
$aviso = json_decode($cru, true);
if (($aviso['tipo'] ?? '') === 'verificacao') { // URL challenge: proof that the route has the key
header('Content-Type: application/json');
echo json_encode(['resposta' => hash_hmac('sha256', 'verificacao.' . $aviso['desafio'], $chave)]);
exit;
}
if ($aviso['teste']) { http_response_code(200); exit; } // dashboard test: do not pay
if (ja_pago($aviso['evento'])) { http_response_code(409); exit; } // already delivered
if (!jogador_existe($aviso['jogador'])) { http_response_code(404); exit; } // the voter fixes the nickname
// the two lines below in the SAME database transaction
dar_premio($aviso['jogador'], 1);
marcar_pago($aviso['evento']);
http_response_code(200);
Python
import hashlib, hmac, json, os, re, time
from flask import Flask, request
app = Flask(__name__)
CHAVE = os.environ.get('IDLEHUB_CHAVE', '')
if not re.fullmatch(r'ih_[0-9A-Za-z]{40}', CHAVE):
raise RuntimeError('IDLEHUB_CHAVE missing or invalid')
def aviso_valido(corpo_cru: bytes, cabecalhos) -> bool:
momento = cabecalhos.get('X-IdleHub-Momento', '')
recebida = cabecalhos.get('X-IdleHub-Assinatura', '')
if not (momento.isascii() and momento.isdigit()) or abs(time.time() - int(momento)) > 300:
return False
esperada = 'sha256=' + hmac.new(CHAVE.encode(),
momento.encode() + b'.' + corpo_cru, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada.encode(), recebida.encode())
@app.post('/idlehub')
def idlehub():
cru = request.get_data()
if not aviso_valido(cru, request.headers):
return '', 401
aviso = json.loads(cru)
if aviso.get('tipo') == 'verificacao': # URL challenge: proof that the route has the key
prova = hmac.new(CHAVE.encode(), ('verificacao.' + aviso['desafio']).encode(), hashlib.sha256).hexdigest()
return {'resposta': prova}, 200
if aviso['teste']:
return '', 200 # dashboard test: do not pay
if ja_pago(aviso['evento']):
return '', 409 # already delivered
if not jogador_existe(aviso['jogador']):
return '', 404 # the voter fixes the nickname
# the two lines below in the SAME database transaction
dar_premio(aviso['jogador'], 1)
marcar_pago(aviso['evento'])
return '', 200
C#
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.RegularExpressions;
app.MapPost("/idlehub", async (HttpRequest req) =>
{
using var leitor = new StreamReader(req.Body, Encoding.UTF8);
var cru = await leitor.ReadToEndAsync();
var momento = req.Headers["X-IdleHub-Momento"].ToString();
var recebida = Encoding.UTF8.GetBytes(req.Headers["X-IdleHub-Assinatura"].ToString());
if (!long.TryParse(momento, out var m) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - m) > 300)
return Results.Unauthorized();
var chaveTexto = Environment.GetEnvironmentVariable("IDLEHUB_CHAVE") ?? "";
if (!Regex.IsMatch(chaveTexto, @"^ih_[0-9A-Za-z]{40}z")) return Results.StatusCode(500); // IDLEHUB_CHAVE missing or invalid
var chave = Encoding.UTF8.GetBytes(chaveTexto);
var hmac = HMACSHA256.HashData(chave, Encoding.UTF8.GetBytes(momento + "." + cru));
var esperada = Encoding.UTF8.GetBytes("sha256=" + Convert.ToHexString(hmac).ToLowerInvariant());
if (!CryptographicOperations.FixedTimeEquals(esperada, recebida)) return Results.Unauthorized();
var aviso = JsonDocument.Parse(cru).RootElement;
if (aviso.TryGetProperty("tipo", out var tipo) && tipo.GetString() == "verificacao") // URL challenge: proof that the route has the key
{
var prova = HMACSHA256.HashData(chave, Encoding.UTF8.GetBytes("verificacao." + aviso.GetProperty("desafio").GetString()));
return Results.Json(new { resposta = Convert.ToHexString(prova).ToLowerInvariant() });
}
if (aviso.GetProperty("teste").GetBoolean()) return Results.Ok(); // dashboard test: do not pay
var evento = aviso.GetProperty("evento").GetString()!;
var jogador = aviso.GetProperty("jogador").GetString()!;
if (JaPago(evento)) return Results.StatusCode(409); // already delivered
if (!JogadorExiste(jogador)) return Results.NotFound(); // the voter fixes the nickname
// the two lines below in the SAME database transaction
DarPremio(jogador, 1);
MarcarPago(evento);
return Results.Ok();
});
The vote button
https://idlehub.io/votar/YOUR-GAME?jogador=NICK opens the vote with the nickname already filled in (encode the nickname with encodeURIComponent/rawurlencode). Without ?jogador=, the player types it. Send only the nickname: never a password, token or email.
The badge with this month's position, for your game's website: https://idlehub.io/api/v1/jogos/YOUR-GAME/selo.svg
Look up a player
GET https://idlehub.io/api/v1/status?jogador=Nick
Authorization: Bearer ih_your_key
{ "jogador": "Nick", "pendentes": 0, "podeGanharDeNovo": false,
"proximaRecompensaEm": "2026-11-16T14:40:11.000Z", "intervaloHoras": 24, ... }
Handy for showing "vote again in 3 h" inside the game.
Public data (no key)
GET https://idlehub.io/api/v1/jogos/YOUR-GAME
{ "jogo": "your-game", "nome": "Your Game", "posicao": 4, "posicaoNaCategoria": 1,
"votosMes": 137, "votos24h": 22, "votosTotal": 2810, ... }
Limits and errors
- 600 requests per minute per key. Beyond that: 429 with
Retry-After. - Errors come as JSON, with the
errofield in Portuguese. - The key stays on your game server. Leaked? Generate a new one in the dashboard: the old one stops working immediately.
- The reward is a bonus, never a requirement to play.