Hlasování přes webhook: napojte i modded server nebo vlastní aplikaci

Votifier nefunguje úplně všude. Modded servery ho často nepodporují a u vlastní aplikace je zbytečně složitý. Proto jsme přidali webhook. V tomto návodu zjistíš, jak funguje a jak si ho nastavíš za pár minut.

---

Hlasování přes Votifier funguje skvěle, ale ne úplně všude. Modded servery (Forge, Fabric, NeoForge) často NuVotifier nepodporují. Na některých hostinzích je otrava otevírat porty. A když si k serveru vedeš vlastní web nebo panel, chceš mít hlasy radši přímo ve svém systému.

Přesně proto jsme přidali webhook. Je to druhý způsob, jak ti doručíme hlas. Místo Votifier protokolu ti pošleme obyčejný požadavek na tvoji URL. A protože jde jen o jednu adresu, zprovozníš to za pár minut.

Co je webhook a jak funguje

Webhook funguje na jednoduchém principu. Pokaždé, když někdo zahlasuje pro tvůj server na minecraft-list.cz, ozveme se tobě. Pošleme požadavek na URL, kterou si nastavíš, a v těle pošleme informace o hlasu ve formátu JSON.

Celý průběh vypadá takto:

1. Hráč zahlasuje pro tvůj server na minecraft-list.cz.
2. My hned pošleme požadavek na tvoji URL s detaily o hlasu.
3. V hlavičce X-Secret přiložíme tvůj tajný klíč, aby sis ověřil, že požadavek je opravdu od nás.
4. Tvůj server hlas zpracuje. Dá odměnu, zapíše ho do databáze, pošle oznámení, cokoliv potřebuješ.
5. Tvůj server odpoví stavovým kódem 2xx a tím je hlas doručený.

Žádný Votifier, žádné otevírání portů. Stačí, aby tvoje URL byla dostupná z internetu, ideálně přes HTTPS.

Pro koho je webhook ideální

• Modded servery (Forge, Fabric, NeoForge), kde NuVotifier nefunguje.
• Vlastní weby a panely, kde chceš mít hlasy přímo ve své aplikaci.
• Vývojáři, kteří si chtějí napojit hlasy na vlastní logiku, frontu odměn nebo žebříček.
• Kdokoliv, kdo nechce řešit porty a chce co nejjednodušší napojení.

Votifier ti samozřejmě zůstává. Webhook je alternativa, ne náhrada. Vyber si, co se ti hodí víc.

Jak webhook nastavit (krok za krokem)

1. Otevři nastavení webhooku. Přihlas se do administrace minecraft-list.cz a v dashboardu svého serveru otevři sekci Webhook.

2. Zadej svoji URL. Do pole Webhook URL napiš adresu, na kterou ti máme hlasy posílat, třeba https://muj-server.cz/vote-webhook. Musí to být veřejně dostupná adresa. Na produkci nepovolíme localhost ani vnitřní IP.

3. Zkopíruj si tajný klíč. Klíč jsme za tebe vygenerovali automaticky. Zkopíruj si ho a nastav stejný i na svém serveru. Budeš jím ověřovat, že požadavek je opravdu od nás. Klíč můžeš kdykoliv změnit tlačítkem Nový.

4. Odešli testovací hlas. Klikni na Odeslat test. Pošleme na tvoji URL ukázkový požadavek a hned uvidíš, jestli endpoint odpověděl správně, nebo co je špatně.

5. Ulož nastavení. Až test projde, klikni na Uložit. Hotovo, od teď ti posíláme každý hlas.

Pokud chceš webhook později vypnout, stačí odškrtnout Webhook aktivní a uložit. URL můžeš nechat klidně prázdnou.

Jak vypadá náš požadavek

Posíláme požadavek typu POST s hlavičkou Content-Type: application/json a tímto tělem:

{
  "event": "vote",
  "vote_id": 12345,
  "username": "Kogol",
  "server": {
    "title": "Můj Server",
    "slug": "muj-server",
    "votes": 1280
  },
  "service": "minecraft-list.cz",
  "timestamp": 1750000000
}

Co která hodnota znamená:

event je typ události, vždy vote.

vote_id je unikátní číslo hlasu. Použij ho na kontrolu duplicit.

username je nick hráče, který hlasoval.

server obsahuje název (title), slug a aktuální počet hlasů (votes) tvého serveru.

service je vždy minecraft-list.cz.

timestamp je čas hlasu jako UNIX timestamp.

V hlavičce X-Secret posíláme tvůj tajný klíč.

Jak ověřit, že je požadavek opravdu od nás

Stačí porovnat hlavičku X-Secret z požadavku s klíčem, který máš nastavený na minecraft-list.cz. Pokud se neshodují, požadavek ignoruj. Díky tomu nikdo cizí nemůže podstrčit falešný hlas.

Na co si dát pozor

Odpovídej kódem 2xx. Jen tak víme, že byl hlas doručený. Přesměrování (3xx) jako úspěch nebereme.

Doručení párkrát zopakujeme. Když to napoprvé nevyjde, zkusíme to znovu, celkem až pětkrát s narůstajícími odstupy: 1 minuta, 5 minut, 15 minut a 1 hodina.

Ošetři duplicity. Kvůli opakování může vzácně dorazit stejný hlas víckrát. Vždy si zkontroluj podle vote_id, jestli jsi ho už nezpracoval.

Hlídáme zdraví tvého endpointu. Když tvoje URL dlouhodobě selhává (10 chyb po sobě), webhook automaticky vypneme a dáme ti vědět, ať nepřicházíš o hlasy potichu. Po opravě stačí webhook zase zapnout.

Používej HTTPS. Tvůj klíč i data hráčů tak zůstanou v bezpečí.

Ukázka zpracování na tvém serveru

Krátký příklad v Node.js (Express), jak hlas přijmout, ověřit a odměnit hráče:

app.post('/vote-webhook', express.json(), (req, res) => {
  // 1) Ověř, že požadavek je od nás
  if (req.get('X-Secret') !== process.env.VOTE_SECRET) {
    return res.sendStatus(401);
  }

  const { vote_id, username } = req.body;

  // 2) Ošetři duplicity (stejný hlas může dorazit víckrát)
  if (alreadyProcessed(vote_id)) {
    return res.sendStatus(200);
  }

  // 3) Odměň hráče, zapiš hlas, pošli na Discord...
  rewardPlayer(username);
  markProcessed(vote_id);

  // 4) Potvrď doručení
  res.sendStatus(200);
});

V jakémkoliv jazyce je princip stejný. Ověř X-Secret, zkontroluj vote_id, zpracuj hlas a vrať 2xx.

Živá ukázka

Chceš vidět webhook v akci? Postavili jsme na něm ukázkovou stránku, která přijímá hlasy přes webhook a hned je zobrazuje v reálném čase. Najdeš na ní žebříček serverů i proud příchozích hlasů, jak naskakují. Přesně takovou věc si můžeš postavit i ty.

Prohlédni si živou ukázku na demo.minecraft-list.cz

Závěr

Webhook je nejjednodušší způsob, jak dostat hlasy z minecraft-list.cz tam, kam potřebuješ. Ať už máš modded server, vlastní aplikaci, nebo se ti prostě nechce řešit Votifier a porty. Nastavení je otázka pár minut.

Podrobný návod na klasické hlasování přes Votifier najdeš v článku Jednoduchý návod jak si propojit hlasování na Minecraft server.

Pokud by ti webhook nefungoval, napiš nám na našem Discordu a rádi pomůžeme. A teď ať ti chodí spousta hlasů!