Minecraft Java Edition

Overview

Connect your Minecraft Java server to topgservers so players who vote on the site automatically receive in-game rewards. The plugin periodically checks the vote-check API and listens for real-time webhooks to grant items, ranks, or currency instantly.

Prerequisites

• A Minecraft server running Bukkit, Spigot, or Paper (1.16+)
• Java 17 or newer
• A topgservers API key — generate one in My Servers → API
• Your webhook secret (optional, for real-time rewards)
• Port 443 outbound access from your server for HTTPS calls

Configuration

# topgservers Vote Plugin Configuration
api-key: "tgs_your_api_key_here"
webhook-secret: "whsec_your_secret_here"
webhook-port: 8090

# Reward command — {player} is replaced with the player's name
reward-command: "give {player} diamond 3"

# Cooldown in hours before a player can be rewarded again
reward-cooldown: 24

# Message sent to the player after reward
reward-message: "&aThanks for voting on topgservers! &7You received 3 diamonds."

Vote Check

Call the /api/v1/vote-check endpoint to determine if a player has voted today.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://topgservers.net/api/v1/vote-check?username=" + playerName))
    .header("Authorization", "Bearer " + apiKey)
    .GET().build();

HttpResponse<String> res =
    http.send(req, HttpResponse.BodyHandlers.ofString());

if (res.statusCode() == 200 && res.body().contains("\"voted\":true")) {
    // Player has voted today — grant reward
}

Webhook Receiver

Verify the X-TopG-Signature header using HMAC-SHA256 to ensure webhook payloads are authentic.

package com.topgservers.vote;

import com.sun.net.httpserver.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.*;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;

public class WebhookListener {
    private final TopGVotePlugin plugin;
    private final String secret;
    private final int port;

    public WebhookListener(TopGVotePlugin plugin, String secret, int port) {
        this.plugin = plugin;
        this.secret = secret;
        this.port = port;
    }

    public void start() {
        try {
            HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);
            server.createContext("/webhook", exchange -> {
                if (!"POST".equals(exchange.getRequestMethod())) {
                    exchange.sendResponseHeaders(405, -1);
                    return;
                }

                String body = new String(
                    exchange.getRequestBody().readAllBytes(),
                    StandardCharsets.UTF_8
                );
                String sigHeader = exchange.getRequestHeaders()
                    .getFirst("X-TopG-Signature");

                if (sigHeader == null || !verifySignature(body, sigHeader)) {
                    exchange.sendResponseHeaders(401, -1);
                    return;
                }

                // Parse username from JSON body (use Gson in production)
                String username = extractField(body, "username");
                if (username != null) {
                    plugin.getServer().getScheduler().runTask(plugin, () -> {
                        plugin.getServer().dispatchCommand(
                            plugin.getServer().getConsoleSender(),
                            "give " + username + " diamond 3"
                        );
                    });
                }

                exchange.sendResponseHeaders(200, -1);
            });
            server.setExecutor(null);
            server.start();
            plugin.getLogger().info("Webhook listener started on port " + port);
        } catch (IOException e) {
            plugin.getLogger().severe("Failed to start webhook listener: " + e.getMessage());
        }
    }

    private boolean verifySignature(String body, String sigHeader) {
        try {
            String[] parts = sigHeader.split(",");
            String timestamp = "", hash = "";
            for (String part : parts) {
                if (part.startsWith("t=")) timestamp = part.substring(2);
                if (part.startsWith("v1=")) hash = part.substring(3);
            }

            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(
                secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] expected = mac.doFinal(
                (timestamp + "." + body).getBytes(StandardCharsets.UTF_8));

            String expectedHex = bytesToHex(expected);
            return expectedHex.equals(hash);
        } catch (Exception e) {
            return false;
        }
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    private static String extractField(String json, String field) {
        int idx = json.indexOf("\"" + field + "\"");
        if (idx == -1) return null;
        int start = json.indexOf(":", idx) + 1;
        int qStart = json.indexOf("\"", start) + 1;
        int qEnd = json.indexOf("\"", qStart);
        return json.substring(qStart, qEnd);
    }
}

Reward Examples

// Diamonds
Bukkit.dispatchCommand(Bukkit.getConsoleSender(),
    "give " + player.getName() + " diamond 3");

// Economy (Vault)
economy.depositPlayer(player, 500.0);

// Permission group (LuckPerms)
Bukkit.dispatchCommand(Bukkit.getConsoleSender(),
    "lp user " + player.getName() + " parent addtemp vip 7d");

// Custom item via Essentials
Bukkit.dispatchCommand(Bukkit.getConsoleSender(),
    "essentials:give " + player.getName() + " vote_crate_key 1");

Notes & Tips

The vote-check endpoint is designed for high-frequency polling (120 req/min). For large servers (100+ concurrent players), consider batching checks every 2–3 minutes instead of every minute. The webhook approach is more efficient for instant rewards and doesn't count against your rate limit.

Resources

• Bukkit Plugin Tutorial
• Paper Documentation
• topgservers API Docs