Webhook

Webhooks in Goxy allow you to send information about players joining your server network and dynamically route them to the appropriate sub-servers. Below, you’ll find instructions on how to set up a custom webhook, example implementations in Java and Node.js, and details about the request and response formats.

🔗Dynamic Player Routing

Use webhooks to automate player routing logic based on their data!

Before You Start

⚠️Advanced Feature

Webhooks are an advanced feature for users familiar with programming and APIs. If you’re unsure how they work, contact us on Discord or consider using Goxy’s default options (e.g., default folder or conditions).

Webhook Configuration

1. Provide the Webhook URL In the Goxy admin panel , go to network settings and enter the URL of your webhook (e.g., https://mc.goxy.io/webhook/join). Note: Once a custom webhook is enabled, Goxy ignores default options (e.g., default folder or conditions).

2. Implement the Webhook Logic Your webhook should receive POST requests with data in JSON format (GoxyJoinRequest) and return a response (GoxyJoinResponse) with the ID of the server to which the player should be redirected.

GoxyJoinRequest – Request Fields

Field	Type	Description
id	string	Identifier of the session or proxy container
networkId	string	Goxy network identifier
protocol	number	Minecraft protocol version (e.g., 761 = 1.20.1)
hostname	string	Domain address from which the player is connecting
realId	string	User identifier in the Goxy system (UUID)
premium	boolean	Whether the player has a premium account (original Mojang/Microsoft)

Example Request

{
  "id": "82b39bee-fd2c-4e60-b877-22fe7b148c36",
  "networkId": "869fad81-b57a-43dc-a7e8-d46aa3340fa4",
  "protocol": 761,
  "hostname": "join.gxy.pl",
  "realId": "99a379bd-b019-4581-8a14-48569f90afd2",
  "premium": false
}

GoxyJoinResponse – Response Fields

Field	Type	Description
id	string	ID of the server (sub-server/sector) to which the player should be routed

Example Response

{
  "id": "d959157b-c22a-47c7-9968-33862db52681"
}

Implementation Examples

Java

Below is an example controller that receives a GoxyJoinRequest and returns a GoxyJoinResponse based on the player’s last sector.

WebhookController.java

@RestController
@RequestMapping("/webhook")
public class WebhookController {

    private final PlayerSectorService playerSectorService;

    public WebhookController(PlayerSectorService playerSectorService) {
        this.playerSectorService = playerSectorService;
    }

    @PostMapping
    public GoxyJoinResponse handleWebhook(@RequestBody GoxyJoinRequest request) {
        // Retrieve the player's last sector
        final Sector lastSector = playerSectorService.getLastSector(request.getRealId());
        // Return a response containing the server ID
        return new GoxyJoinResponse(lastSector.getServerId());
    }
}

Node.js

Below is an example endpoint that processes the request and returns a response with the server ID.

webhookRouter.js

import express, { Request, Response } from "express";
import { PlayerSectorService } from "./playerSectorService";
import { GoxyJoinRequest, GoxyJoinResponse } from "./types";

const router = express.Router();
const playerSectorService = new PlayerSectorService();

router.post("/", (req: Request, res: Response) => {
  const body = req.body as GoxyJoinRequest;

  // retrieve the player's last sector
  const lastSector = playerSectorService.getLastSector(body.realId);

  // prepare the response
  const response: GoxyJoinResponse = {
    id: lastSector.serverId,
  };

  res.json(response);
});

export default router;

Important Notes

⚠️Ignoring Default Options

Once a custom webhook is enabled, Goxy does not consider the default folder or routing conditions. All routing logic depends on your webhook.

ℹ️Testing Your Webhook

Before deploying, test your webhook using tools like Postman to ensure it correctly processes requests and returns responses in JSON format.

⚡ Automation

Route players dynamically using webhooks.

🔧 Flexibility

Integrate the webhook with your own server logic.

🎮 Control

Full control over player redirections.

📎 Links and Resources

🔗Quick Access to Everything

Here are the key links to our resources—all in one place!

Resource	Link
Goxy Homepage	goxy.io
Admin Panel	dashboard.goxy.io
Status Page	status.goxy.io
Discord Community	Join on Discord
Awesome Goxy List	Check the list
API Documentation	API Docs

📢Need Help?

Contact us!
We respond to all messages within 24 hours on Discord.

---

🎉 Use Webhooks to Automate Your Network!

Join Goxy and explore more possibilities!

REGISTER FOR FREE