Prerequisites

This guide assumes you have an approved bot on top.gg and are using either Node.js or Python for your project.

Setting Up the Environment

For Node.js users:

  1. Start a new Node.js project with the following command:
Terminal
npm init -y

This command creates a package.json file in the current directory.

  1. Install the necessary libraries:
Terminal
npm install @top-gg/sdk express

For Python users:

  1. Ensure you have Python and Pip (a package manager for Python) installed on your system. If not, you can download them from the official Python website and the official Pip website.
  2. Install the flask and waitress libraries using pip:
pip install flask
pip install waitress

Setting Up the Project

1. Get your webhook authentication:

  • Go to your Top.gg profile here.
  • Click “edit” on the bot you want to receive notifications for votes.
  • Under “GENERAL”, choose the “webhook” option.
  • Set the webhook authentication in “Authorization”. In this example, we used “myappsquare”.

2. Implement the webhook listener:

The following sections provide code examples for both Javascript and Python:

We will use the example provided by the top.gg documentation here, with some modifications.

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

// Create Express app and Top.gg webhook instances
const app = express();
const webhook = new Topgg.Webhook("YOUR_AUTHORIZATION");

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

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

Managing Dependencies with requirements.txt and package.json Files

The requirements.txt File

The requirements.txt file lists all the external libraries required for your Python project. You should list all the libraries your project will use, excluding the native libraries. This file should be included when submitting your application to Square Cloud.

Just like the package.json is used to manage dependencies in Node.js projects, the requirements.txt is used for the same purpose in Python projects. It helps ensure that all environments where your app runs have the same versions of the required libraries, which helps avoid compatibility issues.

The package.json File

The package.json file lists all the external libraries required for your Node.js project. You should list all the libraries your project will use, excluding the native libraries. This file should be included when submitting your application to Square Cloud.

Conclusion

In both cases, these files make it easy for other developers to set up the environment to run your app, as they can install all dependencies at once using these files.

Creating the squarecloud config file

Learn about: how to make the configuration file for Square Cloud.

The squarecloud.app file is a configuration file that will be used to configure your application; it will be used to define the name, description, version, main file, among other things.

Uploading Your Application to Square Cloud

After following all the steps, put your application files into a zip file, including the configuration file, and upload it to the site at Upload.

If your application is a Node.js project, remember to include the package.json file, but do not include folders or files like node_modules or package-lock.json.

If your application is a Python project, remember to include the requirements.txt file, but do not include folders or files like __pycache__ or .pyc files.

You can get more information about unnecessary files when hosting at automatic-deletion-files-when-deploying-an-application-to-squarecloud.

Troubleshooting

Starting Tests

If you have done everything correctly, try accessing your site using the subdomain defined in the configuration file. If you defined it as “mysite”, to access it will be https://mysite.squareweb.app/. After you access and only “Cannot GET /” or “Method Not Allowed” appears, everything is okay.

Now, you need to go back to the previous page where the authorization was defined. In the Webhook URL field, you should put the URL of your site with the route that will receive the votes.

  • For the JavaScript code we created with app.post("/topgg", webhook.listener((vote) => {...}), the route that will receive the votes is “/topgg”. So, if your website is ”https://mysite.squareweb.app”, you should put ”https://mysite.squareweb.app/topgg” as the Webhook URL.

  • For the Python code we created with @app.route("/topgg", methods=["POST"]), the route that will receive the votes is also “/topgg”. So, the Webhook URL would be the same ”https://mysite.squareweb.app/topgg“.

Finally, click on the “Send Test” button. After that, check the terminal. If everything went well, the message you defined in console.log or print should appear in the terminal.

And with that, if everything has been configured correctly, your webhook will be ready to send notifications when your bot receives a vote on top.gg.

If you continue to experience any issues, please don’t hesitate to contact our support team.