ServerRoamAnmeldenEintragenServer eintragen

Vote-Webhooks

Wenn ein Spieler für deinen Server votet und einen Ingame-Namen eingibt, sendet ServerRoam eine signierte HTTPS-Anfrage an deinen Server. Damit verteilst du eine Belohnung auf FiveM, RedM oder Minecraft.

Einrichten

Beanspruch deinen Server, öffne seine Verwaltungsseite und speichere unter Webhook eine https://-Adresse. Dafür wird ein Signatur-Secret erstellt. Halte das Secret geheim: Wer es hat, kann Votes fälschen. Neues Secret ersetzt es, und das alte funktioniert sofort nicht mehr.

Test-Vote senden stellt ein Event vom Typ test zu, damit du deinen Endpunkt ohne echten Vote prüfen kannst. Das Ergebnis der letzten Zustellung steht auf der Verwaltungsseite.

Anfrage

Eine POST-Anfrage mit JSON-Body:

Body
{
  "event": "vote",
  "id": "48213",
  "server": { "game": "fivem", "slug": "my-roleplay" },
  "username": "Max Power",
  "votedAt": "2026-11-20T14:03:12.481Z"
}

event ist vote für den Vote eines Spielers und test für einen Test von der Verwaltungsseite. id ist für jede Zustellung eindeutig. username ist der Name, den der Spieler eingegeben hat: Minecraft-Namen so, wie Votifier sie annimmt, FiveM- und RedM-Namen ohne Farbcodes, 2 bis 32 Zeichen. votedAt ist der Zeitpunkt des Votes in UTC.

Header: Content-Type: application/json, User-Agent: ServerRoam-Webhook/1 und ServerRoam-Signature: t=<unix seconds>,v1=<signature>.

Signatur prüfen

v1 ist der hexadezimale HMAC-SHA256 von <t>.<raw body> mit deinem Signatur-Secret als Schlüssel. Berechne ihn über den Body genau so, wie er ankommt, bevor du das JSON parst, und vergleiche in konstanter Zeit. Lehne Anfragen ab, deren t mehr als fünf Minuten von deiner Uhr abweicht. Verteile nie eine Belohnung für eine Anfrage, die die Prüfung nicht besteht.

Antworten und Wiederholungen

Antworte innerhalb von 5 Sekunden mit einem beliebigen 2xx-Status. Der Body der Antwort wird ignoriert. Weiterleitungen werden nicht verfolgt und zählen als Fehler, nutze also die endgültige Adresse.

Jeder Vote wird höchstens einmal zugestellt. Kam überhaupt keine Verbindung zustande (DNS, TCP oder TLS schlugen fehl), wird es nach einer Minute und zehn Minuten später noch einmal versucht. Eine gesendete Anfrage wird nie wiederholt, auch wenn dein Endpunkt mit einem Fehler oder nicht rechtzeitig geantwortet hat. Speichere id, wenn du Duplikate trotzdem verwerfen willst.

Jeder Spielername bekommt eine Belohnung pro Server und UTC-Tag. Dein Hostname darf nur auf öffentliche IPv4-Adressen auflösen und muss ein Zertifikat ausliefern, dem Browser vertrauen. IP-Adressen, private Netze und reine IPv6-Hosts werden nicht unterstützt.

Node.js

Ein Empfänger ohne Abhängigkeiten. Betreib ihn hinter deinem HTTPS-Reverse-Proxy und setz SERVERROAM_SECRET.

receiver.mjs
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const secret = process.env.SERVERROAM_SECRET;
const seen = new Set();

function verify(header, body) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${match[1]}.`).update(body).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}

// Runs behind your HTTPS reverse proxy.
createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const body = Buffer.concat(chunks);
    if (req.method !== "POST" || !verify(req.headers["serverroam-signature"], body)) {
      res.writeHead(401).end();
      return;
    }
    const vote = JSON.parse(body.toString("utf8"));
    if (vote.event === "vote" && !seen.has(vote.id)) {
      seen.add(vote.id);
      giveReward(vote.username); // your code
    }
    res.writeHead(204).end();
  });
}).listen(8080);

FiveM und RedM

Eine serverseitige JavaScript-Resource kann Votes direkt empfangen. Speichere beide Dateien in resources/serverroam/ und füg set serverroam_secret "<dein Secret>" und ensure serverroam zur server.cfg hinzu. Nutze set, nicht sets: sets veröffentlicht den Wert in der Serverliste.

FXServer leitet HTTP-Anfragen für /serverroam/ auf seinem Server-Port an diese Resource weiter. Setz über einen Reverse-Proxy, den du selbst betreibst, HTTPS mit einem öffentlich vertrauenswürdigen Zertifikat davor (der Proxy users.cfx.re von cfx.re wird eingestellt). Die Webhook-URL ist diese Adresse, gefolgt von /serverroam/vote.

fxmanifest.lua
fx_version "cerulean"
games { "gta5", "rdr3" }
rdr3_warning "I acknowledge that this is a prerelease build of RedM, and I am aware my resources *will* become incompatible once RedM ships."

server_script "server.js"
server.js
const { createHmac, timingSafeEqual } = require("crypto");

const secret = GetConvar("serverroam_secret", "");

function verify(header, body) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!secret || !match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${match[1]}.`).update(body).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}

SetHttpHandler((req, res) => {
  if (req.method !== "POST" || req.path !== "/vote") {
    res.writeHead(404);
    res.send();
    return;
  }
  req.setDataHandler((data) => {
    const body = Buffer.from(data);
    const header = Object.keys(req.headers).find((name) => name.toLowerCase() === "serverroam-signature");
    if (!verify(header && req.headers[header], body)) {
      res.writeHead(401);
      res.send();
      return;
    }
    const vote = JSON.parse(body.toString("utf8"));
    if (vote.event === "vote") {
      // Listen for this event in your framework and hand out the reward.
      emit("serverroam:vote", vote.username, vote);
    } else {
      console.log(`ServerRoam test vote for ${vote.username}`);
    }
    res.writeHead(204);
    res.send();
  }, "binary");
});

Die Resource löst das Server-Event serverroam:vote mit dem Spielernamen und der Payload aus. Verarbeite es in deinem Framework, um die Belohnung zu vergeben; der Spieler ist beim Eintreffen des Votes womöglich nicht online.