Receive Top.gg Vote Webhooks

​

Introduction

• This guide assumes you have an approved bot on top.gg and are using either Node.js or Python for your project.
• Next, you will need to create an account on Square Cloud, which can be done through the sign up page. You can use your email to create an account.
• Finally, you need to have an active plan on your account. Compare the available plans and choose one according to your needs.

​

Setting up the environment

npm init -y
npm pkg set type=module

npm install express

pip install flask waitress

​

Setting up the project

• Choose the subdomain your application will use on Square Cloud (the SUBDOMAIN field of your configuration file), for example mysite. Your webhook URL will then be https://mysite.squareweb.app/topgg.
• On Top.gg, open your project’s dashboard and go to Webhooks.
• Paste the webhook URL and save. Top.gg then generates a webhook secret that starts with whs_: copy it and keep it private. Your code reads it from the TOPGG_WEBHOOK_SECRET environment variable.

import crypto from "node:crypto";
import express from "express";

const app = express();
// The whs_ secret from your project's Webhooks page on Top.gg
const SECRET = process.env.TOPGG_WEBHOOK_SECRET;

function isValidSignature(rawBody, header = "") {
  // Header format: t=<unix timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
  const timestamp = Number(parts.t);
  if (!SECRET || !Buffer.isBuffer(rawBody) || !parts.v1 || !timestamp) return false;
  // Reject requests older than 5 minutes (replay protection)
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.`).update(rawBody).digest();
  const received = Buffer.from(parts.v1, "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// express.raw keeps the exact bytes Top.gg signed
app.post("/topgg", express.raw({ type: "*/*" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("x-topgg-signature"))) return res.sendStatus(401);

  const { type, data } = JSON.parse(req.body);
  // "vote.create" is a real vote, "webhook.test" comes from the Send Test button
  if (type === "vote.create" || type === "webhook.test") {
    console.log(`Vote received successfully! User ID: ${data.user.platform_id}`);
  }
  res.sendStatus(204);
});

// Square Cloud sets PORT=80 and routes your subdomain's traffic to it
const port = Number(process.env.PORT) || 80;
app.listen(port, "0.0.0.0", () => console.log(`Listening on port ${port}`));

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request
from waitress import serve

app = Flask(__name__)

# The whs_ secret from your project's Webhooks page on Top.gg
SECRET = os.environ.get("TOPGG_WEBHOOK_SECRET", "")


def is_valid_signature(raw_body: bytes, header: str) -> bool:
    # Header format: t=<unix timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = parts["t"]
        signature = parts["v1"]
        age = abs(time.time() - int(timestamp))
    except (KeyError, ValueError):
        return False
    if age > 300:  # reject requests older than 5 minutes (replay protection)
        return False
    message = timestamp.encode() + b"." + raw_body
    expected = hmac.new(SECRET.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), signature.encode())


# Top.gg sends signed POST requests to this route
@app.route("/topgg", methods=["POST"])
def topgg_webhook():
    raw_body = request.get_data()
    if not SECRET or not is_valid_signature(raw_body, request.headers.get("x-topgg-signature", "")):
        abort(401)

    payload = json.loads(raw_body)
    # "vote.create" is a real vote, "webhook.test" comes from the Send Test button
    if payload["type"] in ("vote.create", "webhook.test"):
        print(f'Vote received successfully! User ID: {payload["data"]["user"]["platform_id"]}')
    return "", 204


if __name__ == "__main__":
    # Square Cloud sets PORT=80 and routes your subdomain's traffic to it
    serve(app, host="0.0.0.0", port=int(os.environ.get("PORT", 80)))

​

Creating the squarecloud config file

DISPLAY_NAME=Top.gg Webhook
MAIN=index.js
MEMORY=512
VERSION=recommended
SUBDOMAIN=mysite

DISPLAY_NAME=Top.gg Webhook
MAIN=app.py
MEMORY=512
VERSION=recommended
SUBDOMAIN=mysite

​

Uploading your application to Square Cloud

​

Via dashboard

1

Access the Upload Page

Access the upload page and upload your project zip file.

2

Configure Your Environment

After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.
If you are uploading a web project, make sure to select “Web Publication” and set a subdomain to your project.

3

Deploy Your Project

Finally, click on the “Deploy” button to host your project on Square Cloud.
After deployment, you can monitor your project’s status and logs from the dashboard.

4

Confirm Your App Is Live

Your first deploy usually takes less than a minute. In the dashboard, wait for your application status to show as running and check the logs for any startup errors.
If you deployed a website or API, open https://<your-subdomain>.squareweb.app in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.

App not starting? See the Troubleshooting guide for the most common causes and fixes.

​

Via CLI

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

squarecloud auth login

squarecloud upload

squarecloud upload --file <path/to/zip>

squarecloud app status
squarecloud app logs

​

Setting the webhook secret

• Dashboard: on the upload page, open Advanced configuration and add the variable before you deploy. For an application that is already deployed, add it on its Environment Variables page.
• CLI: from your project folder, set it with squarecloud app env set and restart the application:

squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret
squarecloud app restart

​

Starting tests

• For the JavaScript code we created with app.post("/topgg", ...), the route that will receive the votes is “/topgg”. So, if your website is mysite.squareweb.app, the Webhook URL is https://mysite.squareweb.app/topgg.
• 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 is the same https://mysite.squareweb.app/topgg.

​

Troubleshooting

​

Next steps

​

Contact us