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.
- 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).
- Pon el botón de votar en el juego, con el nick de quien hizo clic:
https://idlehub.io/votar/TU-JUEGO?jogador=NICK - 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}
"tipo": "verificacao"es el desafío de la dirección: llega con el primer Enviar prueba y otra vez después de cambiar la dirección o la clave. Responde 200 con{"resposta": "…"}: el HMAC-SHA256 deverificacao.+desafiocon tu clave, en hex (los ejemplos de abajo ya lo hacen). Sin esa prueba, IdleHub no envía prueba ni voto a la dirección."teste": true(con"tipo": "teste") es el botón Enviar prueba del panel: responde 2xx y no des premio.- Para la regla "1 recompensa por nick", el nick se compara como en una búsqueda sin acentos ni mayúsculas: mayúsculas, acentos, ancho de letra, caracteres invisibles y letras como ø, ł y æ no cuentan — "Fasi", "fasí", "FASI" y "Bjørn"/"Bjorn" son el mismo nick. Tu juego recibe el nick tal como se escribió.
| Tu respuesta | Lo que hace IdleHub |
|---|---|
| 2xx | La marca como entregada. |
| 409 | "Ya lo procesé": también cuenta como entregada. |
| 400, 404, 410, 422 | Jugador 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, 501 | Se detiene en el acto (es un problema de configuración): aparece en el panel, con un botón para reenviar. |
| 429, 5xx, tiempo agotado | Reintenta 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
- 600 solicitudes por minuto por clave. Si pasas de eso: 429 con
Retry-After. - Los errores vienen en JSON, con el campo
erroen portugués. - La clave se queda en el servidor del juego. ¿Se filtró? Genera otra en el panel: la anterior deja de funcionar en el acto.
- La recompensa es un bono, nunca una condición para jugar.