Pular para o conteúdo
Para quem faz jogo

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.

  1. 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).
  2. Ponha o botão de votar no jogo, com o nick de quem clicou: https://idlehub.io/votar/SEU-JOGO?jogador=NICK
  3. 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}
Sua respostaO que o IdleHub faz
2xxMarca como entregue.
409"Já processei": também conta como entregue.
400, 404, 410, 422Jogador 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, 501Para na hora (é configuração): aparece no painel, com botão de reenviar.
429, 5xx, tempo esgotadoTenta 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

Cadastrar meu jogo Meus jogos