Recompensa por voto em 3 passos
Premiar quem vota no seu jogo é o que faz a comunidade voltar a votar todo dia. No IdleHub isso é um webhook: a cada voto, o IdleHub avisa o servidor do jogo na hora, com assinatura, e o jogo entrega o prêmio sozinho. Sem regra contra multi-conta no seu lado — o IdleHub já entrega 1 recompensa por nick a cada 24 h, não importa quantas contas votem no mesmo nick.
- Cadastre o jogo e, depois de aprovado, abra Meus jogos → Recompensa por voto. Ligue a recompensa com o endereço do webhook e copie a chave (ela fica só no servidor do jogo).
- Ponha o botão de votar no jogo, com o nick de quem clicou:
https://idlehub.io/votar/SEU-JOGO?jogador=NICK - Receba o aviso: uma rota no servidor do jogo confere a assinatura e entrega 1 prêmio por voto. A sua IA de código faz essa parte com o prompt logo abaixo.
Implementar com IA
Com IA: copie e cole
Cole no Claude Code, no Cursor, no Copilot ou na IA de código que você usa, aberta na pasta do servidor do jogo: ela lê o seu código e faz a rota do webhook, o botão de votar e o teste. No painel do seu jogo, o mesmo prompt já vem com o nome e o endereço dele.
Ver o prompt
Implemente a recompensa por voto do IdleHub no servidor do meu jogo.
O que é: o IdleHub (https://idlehub.io) é um ranking de jogos idle. Quando alguém vota no meu jogo lá, o IdleHub manda na hora um aviso assinado (webhook) para o servidor do jogo, e o jogo entrega 1 prêmio ao nick que veio no aviso. A fraude fica com o IdleHub: cada nick ganha no máximo 1 recompensa a cada 24 h, não importa quantas contas votem nele. Então é sempre: 1 aviso = 1 prêmio.
Antes de escrever código, leia o projeto e descubra: a linguagem e o framework do servidor, onde ficam as rotas HTTP, o banco de dados, como achar um jogador pelo nick e como dar um item ou uma moeda a ele.
PRÊMIO POR VOTO: [escreva aqui, ex.: 100 moedas]. Se isto continuar entre colchetes, me pergunte qual é o prêmio antes de implementar.
1. A rota do webhook
- POST /idlehub (ou outro caminho que combine com o projeto). Ela precisa ficar pública em HTTPS, na porta 443, no domínio do jogo ou num subdomínio dele.
- Leia o corpo CRU (os bytes exatos, até 64 KB) antes de qualquer leitor de JSON: a assinatura é calculada sobre esses bytes.
- Cabeçalhos:
X-IdleHub-Evento: o id único do aviso (o mesmo valor vem em Idempotency-Key)
X-IdleHub-Momento: o horário do envio, em segundos Unix
X-IdleHub-Assinatura: sha256=<hex>, o HMAC-SHA256 de "<momento>.<corpo cru>" com a chave do jogo
- Confira o momento (no máximo 300 s de diferença do relógio do servidor) e a assinatura, comparando em tempo constante (timingSafeEqual, hash_equals, hmac.compare_digest...). Se falhar, responda 401 e não faça mais nada.
- A chave vem da variável de ambiente IDLEHUB_CHAVE: "ih_" e mais 40 letras e números. Se ela estiver ausente, vazia ou fora desse formato, o servidor não sobe (ou a rota responde 500): nunca confira a assinatura com chave vazia. Nunca a escreva no código, em log nem no repositório.
- O corpo é JSON: {"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"seu-jogo","jogador":"Nick","votadoEm":"2026-11-16T14:32:07.000Z","proximoVotoEm":"2026-11-17T14:32:07.000Z","teste":false}
- "tipo": "verificacao" é o desafio do endereço: chega no 1º "Enviar teste" do painel (e de novo depois de trocar o endereço ou a chave), com {"tipo":"verificacao","desafio":"vrf_...","teste":true}. Trate ANTES de tudo, depois de conferir a assinatura: responda 200 com o JSON {"resposta": "<HMAC-SHA256 do texto "verificacao." + desafio, com a chave, em hex>"} e NÃO dê prêmio. Sem essa resposta, o IdleHub não manda teste nem voto para a rota.
- "teste": true (com "tipo": "teste") é o botão "Enviar teste" do painel do IdleHub: responda 200 e NÃO dê prêmio.
- Guarde cada "evento" pago numa tabela com chave única. O mesmo aviso pode chegar de novo se a resposta se perder: evento repetido = responda 409 e não pague de novo.
- Ache o jogador pelo nick do jeito que o jogo já procura (o nick vem como a pessoa digitou). Não existe = responda 404: quem votou vê o aviso e pode corrigir o nick, e o aviso volta com o MESMO evento.
- Dê o prêmio e grave o evento como pago na MESMA transação. Depois responda 200.
- Responda em até 5 segundos, sem redirecionar.
- Para o IdleHub: 2xx ou 409 = entregue; 400, 404, 410 ou 422 = nick recusado; 401, 403, 405 ou 501 = erro de configuração (ele para e mostra no painel, com botão de reenviar); 429, 5xx ou demora = tenta de novo em 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h.
- Se o servidor fica atrás da Cloudflare ou de outro firewall que bloqueia robôs, libere o POST nessa rota: quem chama é um servidor, sem navegador.
2. O botão de votar
- Na interface do jogo, um botão "Votar no IdleHub" que abre numa aba nova:
https://idlehub.io/votar/seu-jogo?jogador=<nick do jogador logado, codificado para URL>
- Mande só o nick: nunca senha, token ou e-mail.
3. (Opcional) "Vote de novo em X h" dentro do jogo
- Do SERVIDOR do jogo, nunca do navegador: GET https://idlehub.io/api/v1/status?jogador=<nick> com o cabeçalho Authorization: Bearer <IDLEHUB_CHAVE>. A resposta traz "podeGanharDeNovo" e "proximaRecompensaEm".
No fim, me diga: os arquivos que mudaram, o endereço completo da rota para eu cadastrar no painel do IdleHub, onde pôr a IDLEHUB_CHAVE e como testar com o botão "Enviar teste" do painel.
Guia completo: https://idlehub.io/desenvolvedores
O webhook
No painel, cadastre um endereço HTTPS, na porta 443, no domínio do jogo (ou num subdomínio dele). A cada voto, o IdleHub manda:
POST https://api.seujogo.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 de "momento.corpo" com a sua chave>
{"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"seu-jogo","jogador":"Nick",
"votadoEm":"2026-11-15T14:32:07.000Z","proximoVotoEm":"2026-11-16T14:32:07.000Z","teste":false}
"tipo": "verificacao"é o desafio do endereço: chega no 1º Enviar teste e de novo depois de trocar o endereço ou a chave. Responda 200 com{"resposta": "…"}: o HMAC-SHA256 deverificacao.+desafiocom a sua chave, em hex (os exemplos abaixo já fazem isso). Sem essa prova, o IdleHub não manda teste nem voto para o endereço."teste": true(com"tipo": "teste") é o botão Enviar teste do painel: responda 2xx e não dê prêmio.- Para a regra "1 recompensa por nick", o nick é comparado como numa busca sem acento e sem maiúscula: maiúscula, acento, largura de letra, caractere invisível e letras como ø, ł e æ não contam — "Fasi", "fasí", "FASI" e "Bjørn"/"Bjorn" são o mesmo nick. O seu jogo recebe o nick do jeito que foi digitado.
| Sua resposta | O que o IdleHub faz |
|---|---|
| 2xx | Marca como entregue. |
| 409 | "Já processei": também conta como entregue. |
| 400, 404, 410, 422 | Jogador recusado: quem votou vê o aviso e pode corrigir o nick em até 24 h (o aviso volta com o MESMO evento). |
| 401, 403, 405, 501 | Para na hora (é configuração): aparece no painel, com botão de reenviar. |
| 429, 5xx, tempo esgotado | Tenta de novo em 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. |
Responda em até 5 segundos. O IdleHub não segue redirecionamento. Como o mesmo aviso pode chegar mais de uma vez, guarde o evento já pago.
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 ausente ou inválida');
// Guarde o corpo CRU (no 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') { // desafio do endereço: a prova de que a rota tem a chave
return res.json({ resposta: crypto.createHmac('sha256', CHAVE).update('verificacao.' + aviso.desafio).digest('hex') });
}
if (aviso.teste) return res.sendStatus(200); // teste do painel: não paga
if (jaPago(aviso.evento)) return res.sendStatus(409); // já entregue antes
if (!jogadorExiste(aviso.jogador)) return res.sendStatus(404); // quem votou corrige o nick
// as duas linhas abaixo na MESMA transação do banco
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 ausente ou inválida: 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') { // desafio do endereço: a prova de que a rota tem a chave
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; } // teste do painel: não paga
if (ja_pago($aviso['evento'])) { http_response_code(409); exit; } // já entregue antes
if (!jogador_existe($aviso['jogador'])) { http_response_code(404); exit; } // quem votou corrige o nick
// as duas linhas abaixo na MESMA transação do banco
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 ausente ou inválida')
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': # desafio do endereço: a prova de que a rota tem a chave
prova = hmac.new(CHAVE.encode(), ('verificacao.' + aviso['desafio']).encode(), hashlib.sha256).hexdigest()
return {'resposta': prova}, 200
if aviso['teste']:
return '', 200 # teste do painel: não paga
if ja_pago(aviso['evento']):
return '', 409 # já entregue antes
if not jogador_existe(aviso['jogador']):
return '', 404 # quem votou corrige o nick
# as duas linhas abaixo na MESMA transação do banco
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 ausente ou inválida
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") // desafio do endereço: a prova de que a rota tem a chave
{
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(); // teste do painel: não paga
var evento = aviso.GetProperty("evento").GetString()!;
var jogador = aviso.GetProperty("jogador").GetString()!;
if (JaPago(evento)) return Results.StatusCode(409); // já entregue antes
if (!JogadorExiste(jogador)) return Results.NotFound(); // quem votou corrige o nick
// as duas linhas abaixo na MESMA transação do banco
DarPremio(jogador, 1);
MarcarPago(evento);
return Results.Ok();
});
O botão de votar
https://idlehub.io/votar/SEU-JOGO?jogador=NICK abre a votação com o nick já preenchido (codifique o nick com encodeURIComponent/rawurlencode). Sem ?jogador=, a pessoa digita. Mande só o nick: nunca senha, token ou e-mail.
O selo com a posição do mês, para o site do jogo: https://idlehub.io/api/v1/jogos/SEU-JOGO/selo.svg
Consultar um jogador
GET https://idlehub.io/api/v1/status?jogador=Nick
Authorization: Bearer ih_sua_chave
{ "jogador": "Nick", "pendentes": 0, "podeGanharDeNovo": false,
"proximaRecompensaEm": "2026-11-16T14:40:11.000Z", "intervaloHoras": 24, ... }
Bom para mostrar "vote de novo em 3 h" dentro do jogo.
Dados públicos (sem chave)
GET https://idlehub.io/api/v1/jogos/SEU-JOGO
{ "jogo": "seu-jogo", "nome": "Seu Jogo", "posicao": 4, "posicaoNaCategoria": 1,
"votosMes": 137, "votos24h": 22, "votosTotal": 2810, ... }
Limites e erros
- 600 pedidos por minuto por chave. Passou disso: 429 com
Retry-After. - Erros vêm em JSON com o campo
erroem português. - A chave fica no servidor do jogo. Vazou? Gere outra no painel: a anterior para na hora.
- A recompensa é um bônus, nunca condição para jogar.