ServerRoamSign inSubmit server

Vote webhooks

When a player votes for your server and enters an in-game name, ServerRoam sends a signed HTTPS request to your server. Use it to hand out a reward on FiveM, RedM or Minecraft.

Set it up

Claim your server, open its manage page and save an https:// address under Webhook. A signing secret is created for it. Keep the secret private: anyone who has it can forge votes. New secret replaces it, and the old one stops working at once.

Send test vote delivers an event of type test, so you can check your endpoint without a real vote. The outcome of the last delivery is shown on the manage page.

Request

A POST request with a JSON body:

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

event is vote for a player's vote and test for a test from the manage page. id is unique per delivery. username is the name the player entered: Minecraft names as Votifier accepts them, FiveM and RedM names without colour codes, 2 to 32 characters. votedAt is the time of the vote in UTC.

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

Verify the signature

v1 is the hex HMAC-SHA256 of <t>.<raw body>, keyed with your signing secret. Compute it over the body exactly as received, before parsing the JSON, and compare in constant time. Reject requests whose t is more than five minutes away from your clock. Never hand out a reward for a request that fails the check.

Responses and retries

Answer with any 2xx status within 5 seconds. The response body is ignored. Redirects are not followed and count as a failure, so use the final address.

Each vote is delivered at most once. If no connection could be made at all (DNS, TCP or TLS failed), it is tried again after one minute and once more ten minutes later. A request that was sent is never repeated, even when your endpoint answered with an error or did not answer in time. Store id if you want to drop duplicates anyway.

Each player name gets one reward per server and UTC day. Your hostname has to resolve to public IPv4 addresses only and serve a certificate that browsers trust. IP addresses, private networks and IPv6-only hosts are not supported.

Node.js

A receiver without dependencies. Put it behind your HTTPS reverse proxy and set 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 and RedM

A server-side JavaScript resource can receive votes directly. Save both files in resources/serverroam/ and add set serverroam_secret "<your secret>" and ensure serverroam to server.cfg. Use set, not sets: sets publishes the value in the server list.

FXServer passes HTTP requests for /serverroam/ on its server port to this resource. Put HTTPS with a publicly trusted certificate in front of it through a reverse proxy you run (cfx.re's users.cfx.re proxy is being retired). The webhook URL is that address followed by /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");
});

The resource emits the server event serverroam:vote with the player name and the payload. Handle it in your framework to give the reward; the player may not be online when the vote arrives.