How to Set Up Webhooks and Notifications for Your Hytale Server

HytaleCharts provides several integration options that let you connect your Hytale server listing to Discord, your game server, and external tools. When a player votes for your server, you can receive a Discord notification, trigger in-game rewards via Votifier, fire a custom webhook to your own backend, and keep your server status up-to-date with the heartbeat plugin. This guide covers how to set up each integration from scratch. All of these features are accessible from your server's edit page on HytaleCharts after logging in as the server owner or a team member. Discord Vote Webhooks Discord webhooks let you receive a notification in a Discord channel every time someone votes for, favorites, or leaves a review on your server listing. Setting Up Discord Webhooks Create a webhook in your Discord server. Go to Server Settings, then Integrations, then Webhooks. Click "New Webhook," give it a name (e.g., "HytaleCharts Votes"), choose the channel, and copy the webhook URL. Add the webhook URL on HytaleCharts. Go to your server's edit page, find the Discord Webhook section, and paste the URL. Save your settings. HytaleCharts will now send a formatted embed to your Discord channel whenever a vote, favorite, or review event occurs. What Gets Sent Each webhook notification is sent as a Discord embed containing: The type of event (vote, favorite, review) The username of the player who performed the action A timestamp Your server name and a link back to your HytaleCharts listing Webhook delivery uses a retry system with 3 attempts and a 5-second backoff between retries. If all attempts fail, the failure is logged, and HytaleCharts tracks consecutive failures per server. If a webhook URL consistently fails (returns HTTP errors or times out), it will eventually be flagged so you can update or fix it. Votifier: In-Game Vote Rewards Votifier is a protocol that sends vote notifications directly to your game server, allowing you to reward players in-game when they vote on HytaleCharts. HytaleCharts supports three Votifier variants. Votifier v1 (RSA Encrypted) The original Votifier protocol uses RSA encryption. When a vote is cast, HytaleCharts encrypts a vote message with your server's public key and sends it via TCP. To set up Votifier v1: Install a Votifier-compatible plugin on your Hytale server Generate an RSA key pair (the plugin usually does this automatically on first run) Copy your public key from the plugin's configuration On HytaleCharts, go to your server's edit page and set the Votifier type to "v1" Enter your server's host (IP address or domain), port (the Votifier listening port, not the game port), and paste the public key Save and use the "Test Connection" button to verify it works The vote message follows the standard Votifier format: VOTE\nHytaleCharts\n{username}\n{ip_address}\n{timestamp}\n, encrypted with PKCS#1 v1.5 padding. Votifier v2 (HMAC-SHA256) Votifier v2 is the more modern protocol. Instead of RSA encryption, it uses HMAC-SHA256 signing with a shared token. The handshake includes a challenge string from the server to prevent replay attacks. To set up Votifier v2: Install a v2-compatible Votifier plugin Find the token (shared secret) in the plugin's configuration file On HytaleCharts, set the Votifier type to "v2" Enter your server's host, port, and token Save and test the connection The v2 protocol connects via TCP, reads a handshake greeting with a challenge token, then sends a binary packet containing a JSON payload signed with HMAC-SHA256. The payload includes the service name ("HytaleCharts"), username, IP address, timestamp in milliseconds, and the challenge string. HTTP Votifier For Hytale-specific plugins that use HTTP instead of raw TCP, HytaleCharts supports an HTTP endpoint mode. This is the simplest protocol to implement for plugin developers. To set up HTTP Votifier: Install a plugin that exposes an HTTP endpoint for receiving votes On HytaleCharts, set the Votifier type to "HTTP" Enter the full endpoint URL (e.g., https://your-server.com:8080/vote) If the plugin requires a token, enter it in the token field. HytaleCharts will sign the request with an HMAC-SHA256 signature in the X-Votifier-Signature header. Save and test The HTTP request sends a JSON body with serviceName, username, address, and timestamp fields. Important Notes for All Votifier Types Usernames are truncated to 16 characters to match Hytale's username limit. HytaleCharts uses the player's Hytale username if set, otherwise their Discord username. Connection timeout is 5 seconds. If your server does not respond within 5 seconds, the attempt is considered failed. Failed attempts retry up to 3 times with exponential backoff (10s, 30s, 60s between attempts). You can use the Test Connection button on HytaleCharts to verify your setup without needing a real vote. This checks that the server is reachable and responds with the expected Votifier handshake. Generic Webhooks If you want to send vote notifications to your own backend service, bot, or application, generic webhooks let you define a custom URL and payload template. How Generic Webhooks Work On your server's edit page, navigate to the webhook configuration section Enter the URL of your endpoint Configure the payload template with the data you want to receive Save your settings When a vote event occurs, HytaleCharts sends an HTTP POST request to your URL with the configured payload. The system supports template variables that are replaced with actual values at send time (voter username, server name, timestamp, etc.). Generic webhooks use the same retry logic as Discord webhooks: 3 attempts with progressive backoff (10s, then 30s between retries). If all retries fail, the failure is tracked against your server, and persistent failures will be flagged in your dashboard. Heartbeat Plugin: Online Status Tracking The HytaleCharts heartbeat plugin runs on your game server and sends periodic status updates so your listing always shows accurate online/offline status and player counts. How It Works The plugin sends a heartbeat to https://hytalecharts.com/api/heartbeat every 5 minutes (or every 20 seconds for premium servers). Each heartbeat includes: Your server's heartbeat secret (a 64-character hex token) Current player count and max players A players array with individual player details (username, UUID, world, ping) Server metadata like server name, MOTD, uptime, and memory usage A list of installed plugins and world names Setup Steps Generate a heartbeat secret. On your server's edit page, go to the Heartbeat section and click "Generate Secret." This creates a unique 64-character token. Install the plugin. Place the HytaleCharts plugin in your server's mods/ directory. Configure the plugin. Edit the plugin's config.json file and set the secret: { "secret": "YOUR_64_CHAR_HEARTBEAT_SECRET", "debug": false } Restart your server. The plugin will begin sending heartbeats immediately. Verify on HytaleCharts. Check your server's edit page; it should show the last heartbeat timestamp and indicate that the connection is active. Multi-Server Aggregation If you run multiple server instances (lobby, survival, creative) sharing the same heartbeat secret, HytaleCharts automatically aggregates them. It identifies distinct instances by their IP address and server name, takes the latest heartbeat from each, and merges players by UUID to avoid double-counting. The total player count and max players shown on your listing reflect the combined values across all instances. Online Status Priority HytaleCharts determines your server's online status using a priority system: External query endpoint (if configured, e.g., Nitrado query API) Heartbeat plugin (server shows as online if a heartbeat was received within the last 5 minutes) UDP ping (fallback server query) If the heartbeat plugin goes silent for more than 5 minutes and no external query is configured, the server falls back to UDP ping status. Public Server API Tokens HytaleCharts provides a public API that lets you query voter data, server stats, and other information programmatically. To use it, you need an API token. Getting Your API Token Go to your server's edit page on HytaleCharts Navigate to the API section Generate an API token Copy and store it securely. The token authenticates all requests to the public server API endpoints. Using the API Include the token in the Authorization header of your API requests: GET /api/public/servers/{server_id}/voters Authorization: Bearer YOUR_API_TOKEN The public API lets you fetch recent voters, server statistics, and other data that you can use to build custom integrations, leaderboards, or reward systems on your server. For complete API documentation and endpoint details, check the Server API page on HytaleCharts. Troubleshooting IssuePossible CauseSolution Discord webhook not sendingInvalid webhook URLDelete and recreate the webhook in Discord, then update the URL on HytaleCharts Votifier test fails with "No response"Firewall blocking the Votifier portEnsure the Votifier port (not the game port) is open in your firewall Votifier test says "Invalid V2 handshake"Server only supports v1 but you selected v2Change the Votifier type to v1 and provide the RSA public key instead of a token Heartbeat not registeringWrong secret in plugin configDouble-check that the secret in config.json matches the one shown on HytaleCharts exactly Player count shows 0Plugin version older than 1.5.0Update the HytaleCharts plugin to the latest version, which sends individual player data Webhook marked as failing100+ consecutive failuresFix the endpoint URL, then test it. Successful delivery resets the failure counter. If you run into issues not covered here, reach out via the contact form on HytaleCharts. We can check your server's webhook logs and heartbeat history to help diagnose problems. Setting up these integrations takes a few minutes but significantly improves how your server interacts with HytaleCharts and your community. Servers with active vote notifications and in-game rewards consistently see higher engagement and return visits from voters. Browse other server listings to see how top servers describe their integration features, and make sure your own listing mentions what you have set up.