How to Create a Top.gg Webhook on Square Cloud

Webhooks are fundamental for integrating your bot with external services. In the case of Top.gg, whenever a user votes for your bot, their server sends a POST request to your application. On Square Cloud, you can host this webhook stably on port 80.

1. How Does the Communication Work?

When a vote occurs, Top.gg acts as the client and your application on Square Cloud acts as the server.

1. User votes on Top.gg.
2. Top.gg sends a data packet (JSON) to your application's URL.
3. Your Application validates if the request is legitimate (via Authorization Token) and processes the vote.

2. Implementation in JavaScript (Express)

Express is the most common choice due to its simplicity in handling HTTP routes. Top.gg offers a package to assist with this task; install it with the command below and then check out the usage example:

npm install @top-gg/sdk express

// Import libraries
const Topgg = require("@top-gg/sdk");
const express = require("express");

// Create the Express application and the Top.gg webhook instance
const app = express();
const webhook = new Topgg.Webhook("YOUR_AUTHORIZATION_TOKEN");

// Define the route for the '/webhook' endpoint (POST requests)
app.post("/webhook", webhook.listener((vote) => {
  console.log(`Vote successfully received! User ID: ${vote.user}`);
}));

// Start the server on port 80
app.listen(80);

3. Implementation in Python (Flask)

For those who prefer Python, Flask offers a lightweight and straightforward solution.

from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def topgg_webhook():
    # Token Verification
    auth_header = request.headers.get('Authorization')
    topgg_token = os.getenv('TOPGG_AUTH')

    if auth_header == topgg_token:
        data = request.json
        user_id = data.get('user')
        print(f"Vote confirmed for user: {user_id}")
        
        return jsonify({"status": "success"}), 200
    else:
        return jsonify({"error": "unauthorized"}), 401

if __name__ == '__main__':
    # Required configuration for Square Cloud
    app.run(host='0.0.0.0', port=80)

4. Configuration on Square Cloud

For the webhook to work, you must configure your application as a Webserver:

1. Deployment: Upload your code (remember not to send node_modules or venv).
2. Publish to Web: In the Dashboard submission menu, enable the "Publish to Web" option.
3. Subdomain: Define a name (e.g., topgg-webhook). Your final URL will be https://topgg-webhook.squareweb.app/webhook.
4. Environment Variables (ENV): Add the TOPGG_AUTH key with the token you will create on the Top.gg website.

5. Configuration on the Top.gg Panel

1. Go to your bot's edit page on Top.gg.
2. Look for the Webhooks tab.
3. In the Webhook URL field, paste the URL generated by Square Cloud (e.g., https://topgg-webhook.squareweb.app/webhook).
4. In the Authorization field, create a password/token and save it (remember to put this same password in the Square Cloud ENV).
5. Click Test to send a test vote and check if it appears in your Dashboard logs.

6. Best Practices

• Security: Never expose the authorization token in your code. Always use environment variables.
• Logs: Keep logs of received requests to be able to debug if a vote is not processed.
• Error Handling: Always respond with 200 OK quickly. If your reward logic is time-consuming, process it asynchronously to avoid causing a timeout on the Top.gg server.

```

Updated on: 05/26/2026