Saltar al contenido
Para quien hace juegos

Recompensa por voto en 3 pasos

Premiar a quien vota por tu juego es lo que hace que la comunidad vuelva a votar cada día. En IdleHub es un webhook: con cada voto, IdleHub avisa al servidor del juego al instante, con firma, y el juego entrega el premio solo. Sin reglas contra multicuentas de tu lado — IdleHub ya entrega 1 recompensa por nick cada 24 h, sin importar cuántas cuentas voten por el mismo nick.

  1. Envía tu juego y, cuando esté aprobado, abre Mis juegos → Recompensa por voto. Activa la recompensa con la dirección del webhook y copia la clave (se queda solo en el servidor del juego).
  2. Pon el botón de votar en el juego, con el nick de quien hizo clic: https://idlehub.io/votar/TU-JUEGO?jogador=NICK
  3. Recibe el aviso: una ruta en el servidor del juego verifica la firma y entrega 1 premio por voto. Tu IA de código hace esta parte con el prompt de abajo.

Implementar con IA

Con IA: copia y pega

Pégalo en Claude Code, Cursor, Copilot o la IA de código que uses, abierta en la carpeta del servidor del juego: lee tu código y hace la ruta del webhook, el botón de votar y la prueba. En el panel de tu juego, el mismo prompt ya viene con su nombre y su dirección.

Ver el prompt
Implementa la recompensa por voto de IdleHub en el servidor de mi juego.

Qué es: IdleHub (https://idlehub.io) es un ranking de juegos idle. Cuando alguien vota por mi juego allí, IdleHub envía al instante un aviso firmado (webhook) al servidor del juego, y el juego entrega 1 premio al nick que vino en el aviso. El fraude lo controla IdleHub: cada nick gana como máximo 1 recompensa cada 24 h, sin importar cuántas cuentas voten por él. Así que siempre es: 1 aviso = 1 premio.

Antes de escribir código, lee el proyecto y averigua: el lenguaje y el framework del servidor, dónde están las rutas HTTP, la base de datos, cómo encontrar a un jugador por su nick y cómo darle un objeto o una moneda.

PREMIO POR VOTO: [escríbelo aquí, ej.: 100 monedas]. Si esto sigue entre corchetes, pregúntame cuál es el premio antes de implementar.

1. La ruta del webhook
- POST /idlehub (u otra ruta que encaje con el proyecto). Debe ser pública en HTTPS, en el puerto 443, en el dominio del juego o en un subdominio.
- Lee el cuerpo CRUDO (los bytes exactos, hasta 64 KB) antes de cualquier lector de JSON: la firma se calcula sobre esos bytes.
- Cabeceras:
  X-IdleHub-Evento: el id único del aviso (el mismo valor viene en Idempotency-Key)
  X-IdleHub-Momento: la hora del envío, en segundos Unix
  X-IdleHub-Assinatura: sha256=<hex>, el HMAC-SHA256 de "<momento>.<cuerpo crudo>" con la clave del juego
- Verifica el momento (como máximo 300 s de diferencia con el reloj del servidor) y la firma, comparando en tiempo constante (timingSafeEqual, hash_equals, hmac.compare_digest...). Si falla, responde 401 y no hagas nada más.
- La clave viene de la variable de entorno IDLEHUB_CHAVE: "ih_" y 40 letras y números más. Si falta, está vacía o tiene otro formato, el servidor no arranca (o la ruta responde 500): nunca verifiques la firma con una clave vacía. Nunca la escribas en el código, en logs ni en el repositorio.
- El cuerpo es JSON: {"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"tu-juego","jogador":"Nick","votadoEm":"2026-11-16T14:32:07.000Z","proximoVotoEm":"2026-11-17T14:32:07.000Z","teste":false}
- "tipo": "verificacao" es el desafío de la dirección: llega con el primer "Enviar prueba" del panel (y otra vez después de cambiar la dirección o la clave), como {"tipo":"verificacao","desafio":"vrf_...","teste":true}. Trátalo ANTES de todo, después de verificar la firma: responde 200 con el JSON {"resposta": "<HMAC-SHA256 del texto "verificacao." + desafio, con la clave, en hex>"} y NO des premio. Sin esa respuesta, IdleHub no envía prueba ni voto a la ruta.
- "teste": true (con "tipo": "teste") es el botón "Enviar prueba" del panel de IdleHub: responde 200 y NO des premio.
- Guarda cada "evento" pagado en una tabla con clave única. El mismo aviso puede llegar de nuevo si la respuesta se pierde: evento repetido = responde 409 y no pagues otra vez.
- Busca al jugador por el nick como el juego ya lo hace (el nick llega tal como la persona lo escribió). No existe = responde 404: quien votó ve el aviso y puede corregir el nick, y el aviso vuelve con el MISMO evento.
- Da el premio y guarda el evento como pagado en la MISMA transacción. Después responde 200.
- Responde en menos de 5 segundos, sin redirigir.
- Para IdleHub: 2xx o 409 = entregado; 400, 404, 410 o 422 = nick rechazado; 401, 403, 405 o 501 = error de configuración (se detiene y lo muestra en el panel, con botón de reenviar); 429, 5xx o demora = reintenta en 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h.
- Si el servidor está detrás de Cloudflare o de otro firewall que bloquea bots, permite el POST en esta ruta: quien llama es un servidor, sin navegador.

2. El botón de votar
- En la interfaz del juego, un botón "Votar en IdleHub" que abre en una pestaña nueva:
  https://idlehub.io/votar/tu-juego?jogador=<nick del jugador conectado, codificado para URL>
- Envía solo el nick: nunca contraseña, token ni correo.

3. (Opcional) "Vota de nuevo en X h" dentro del juego
- Desde el SERVIDOR del juego, nunca desde el navegador: GET https://idlehub.io/api/v1/status?jogador=<nick> con la cabecera Authorization: Bearer <IDLEHUB_CHAVE>. La respuesta trae "podeGanharDeNovo" y "proximaRecompensaEm".

Al terminar, dime: los archivos que cambiaste, la dirección completa de la ruta para registrarla en el panel de IdleHub, dónde poner IDLEHUB_CHAVE y cómo probar con el botón "Enviar prueba" del panel.
Guía completa: https://idlehub.io/desenvolvedores

El webhook

En el panel, registra una dirección HTTPS, en el puerto 443, en el dominio del juego (o en un subdominio). Con cada voto, IdleHub envía:

POST https://api.tujuego.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" con tu clave>

{"tipo":"voto","evento":"evt_8Kd2mQ1xTn9rAb3cDe","jogo":"tu-juego","jogador":"Nick",
 "votadoEm":"2026-11-15T14:32:07.000Z","proximoVotoEm":"2026-11-16T14:32:07.000Z","teste":false}
Tu respuestaLo que hace IdleHub
2xxLa marca como entregada.
409"Ya lo procesé": también cuenta como entregada.
400, 404, 410, 422Jugador rechazado: quien votó ve el aviso y puede corregir el nick en hasta 24 h (el aviso vuelve con el MISMO evento).
401, 403, 405, 501Se detiene en el acto (es un problema de configuración): aparece en el panel, con un botón para reenviar.
429, 5xx, tiempo agotadoReintenta a los 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h.

Responde en hasta 5 segundos. IdleHub no sigue redirecciones. Como el mismo aviso puede llegar más de una vez, guarda cada evento ya pagado.

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 o inválida');

// Guarda el cuerpo CRUDO (en 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') {                            // desafío de la dirección: la prueba de que la ruta tiene la clave
    return res.json({ resposta: crypto.createHmac('sha256', CHAVE).update('verificacao.' + aviso.desafio).digest('hex') });
  }
  if (aviso.teste) return res.sendStatus(200);                   // prueba del panel: no se paga
  if (jaPago(aviso.evento)) return res.sendStatus(409);          // ya entregado antes
  if (!jogadorExiste(aviso.jogador)) return res.sendStatus(404); // quien votó corrige el nick
  // las dos líneas de abajo en la MISMA transacción de la base de datos
  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 o 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') {                             // desafío de la dirección: la prueba de que la ruta tiene la clave
  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; }                     // prueba del panel: no se paga
if (ja_pago($aviso['evento'])) { http_response_code(409); exit; }           // ya entregado antes
if (!jogador_existe($aviso['jogador'])) { http_response_code(404); exit; }  // quien votó corrige el nick
// las dos líneas de abajo en la MISMA transacción de la base de datos
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 o 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':  # desafío de la dirección: la prueba de que la ruta tiene la clave
        prova = hmac.new(CHAVE.encode(), ('verificacao.' + aviso['desafio']).encode(), hashlib.sha256).hexdigest()
        return {'resposta': prova}, 200
    if aviso['teste']:
        return '', 200  # prueba del panel: no se paga
    if ja_pago(aviso['evento']):
        return '', 409  # ya entregado antes
    if not jogador_existe(aviso['jogador']):
        return '', 404  # quien votó corrige el nick
    # las dos líneas de abajo en la MISMA transacción de la base de datos
    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 o 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")   // desafío de la dirección: la prueba de que la ruta tiene la clave
    {
        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();   // prueba del panel: no se paga
    var evento = aviso.GetProperty("evento").GetString()!;
    var jogador = aviso.GetProperty("jogador").GetString()!;
    if (JaPago(evento)) return Results.StatusCode(409);                 // ya entregado antes
    if (!JogadorExiste(jogador)) return Results.NotFound();             // quien votó corrige el nick
    // las dos líneas de abajo en la MISMA transacción de la base de datos
    DarPremio(jogador, 1);
    MarcarPago(evento);
    return Results.Ok();
});

El botón de votar

https://idlehub.io/votar/TU-JUEGO?jogador=NICK abre la votación con el nick ya completado (codifica el nick con encodeURIComponent/rawurlencode). Sin ?jogador=, la persona lo escribe. Envía solo el nick: nunca contraseña, token ni correo.

El sello con la posición del mes, para el sitio del juego: https://idlehub.io/api/v1/jogos/TU-JUEGO/selo.svg

Consultar un jugador

GET https://idlehub.io/api/v1/status?jogador=Nick
Authorization: Bearer ih_tu_clave

{ "jogador": "Nick", "pendentes": 0, "podeGanharDeNovo": false,
  "proximaRecompensaEm": "2026-11-16T14:40:11.000Z", "intervaloHoras": 24, ... }

Útil para mostrar "vuelve a votar en 3 h" dentro del juego.

Datos públicos (sin clave)

GET https://idlehub.io/api/v1/jogos/TU-JUEGO

{ "jogo": "tu-juego", "nome": "Tu Juego", "posicao": 4, "posicaoNaCategoria": 1,
  "votosMes": 137, "votos24h": 22, "votosTotal": 2810, ... }

Límites y errores

Enviar mi juego Mis juegos