Integrando o voto no seu jogo

No painel do seu jogo você encontra um link no formato abaixo. Troque PLAYER_ID pelo identificador do jogador no seu próprio sistema — não precisa ser nada especial, só algo que você reconheça depois.

https://idlerank.com/vote/seu-jogo?ref=SUA_CHAVE_PUBLICA&player=PLAYER_ID

Abra esse link (num navegador embutido, numa nova aba, como preferir) quando o jogador clicar em "votar". Se ele ainda não tiver conta no IdleRank, pedimos login com Google ou Discord antes de confirmar — depois disso o voto é registrado e contabilizado no ranking.

Assim que o voto é confirmado, se você tiver uma URL de webhook configurada no painel, enviamos um POST assinado para ela:

{
  "event": "vote.created",
  "gameId": "5b1e...",
  "timestamp": "2026-08-08T20:14:03.000Z",
  "data": {
    "externalPlayerId": "player_123",
    "voteId": "9f2a...",
    "votedAt": "2026-08-08T20:14:03.000Z"
  }
}

A assinatura vai no header X-IdleRank-Signature, no formato sha256=<hmac hex>, calculada com o seu segredo de assinatura do webhook. Ele aparece separado da chave secreta da API e pode ser revelado no painel do proprietário. Sempre verifique a assinatura antes de confiar no payload:

// Node.js / Express — verificando a assinatura do webhook
import crypto from "crypto";

app.post("/api/idlerank-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-idlerank-signature"]; // "sha256=..."
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.IDLERANK_WEBHOOK_SECRET)
    .update(req.body) // Buffer cru, sem JSON.parse
    .digest("hex");

  const ok = signature?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body);
  if (event.event === "vote.created") {
    const { externalPlayerId } = event.data;
    // credite a recompensa para externalPlayerId aqui
  }

  res.status(200).send("ok");
});

Cada entrega inclui o mesmo voteId no payload, em X-IdleRank-Vote-Id e no header Idempotency-Key. Guarde esse identificador para não recompensar duas vezes caso um evento seja reenviado. Falhas transitórias são tentadas novamente com espaçamento crescente; eventos nunca entregues também podem ser reenviados pelo painel.

Se quiser mostrar "você já votou hoje" dentro do seu próprio jogo, sem esperar o redirecionamento, use sua chave secreta para consultar:

GET https://idlerank.com/api/v1/games/seu-jogo/vote-status?player=PLAYER_ID
Authorization: Bearer SUA_CHAVE_SECRETA

E para estatísticas públicas do jogo (sem autenticação), útil para mostrar sua colocação atual dentro do próprio jogo:

GET https://idlerank.com/api/v1/games/seu-jogo

De propósito. Se qualquer servidor pudesse creditar votos sem um jogador real passar pelo IdleRank, o ranking perderia sentido — e é o ranking que traz visibilidade pro seu jogo. O fluxo por link garante que cada voto corresponde a uma pessoa de verdade chegando até aqui.

• Cada jogador pode votar em cada jogo uma vez a cada 24 horas, ou a cada 12 horas quando Ouro ou Diamante estiver ativo.
• Webhooks têm timeout de 8 segundos e até 4 tentativas.
• URLs de webhook precisam ser HTTPS.