Ricevi i webhook dei voti di Top.gg

​

Introduzione

• Questa guida presuppone che tu abbia un bot approvato su top.gg e che stia utilizzando Node.js o Python per il tuo progetto.
• Successivamente, dovrai creare un account su Square Cloud, cosa che puoi fare tramite la pagina di registrazione. Puoi usare la tua email per creare un account.
• Infine, devi avere un piano attivo sul tuo account. Confronta i piani disponibili e scegline uno in base alle tue esigenze.

​

Configurare l’ambiente

npm init -y
npm pkg set type=module

npm install express

pip install flask waitress

​

Configurare il progetto

• Scegli il sottodominio che la tua applicazione userà su Square Cloud (il campo SUBDOMAIN del tuo file di configurazione), per esempio mysite. L’URL del tuo webhook sarà quindi https://mysite.squareweb.app/topgg.
• Su Top.gg, apri la dashboard del tuo progetto e vai su Webhooks.
• Incolla l’URL del webhook e salva. Top.gg genera quindi un webhook secret che inizia con whs_: copialo e tienilo privato. Il tuo codice lo legge dalla variabile d’ambiente TOPGG_WEBHOOK_SECRET.

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)))

​

Creare il file di configurazione squarecloud

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

​

Caricare l’applicazione su Square Cloud

​

Tramite dashboard

1

Accedi alla pagina di upload

Accedi alla pagina di upload e carica il file zip del tuo progetto.

2

Configura il tuo ambiente

Dopo aver caricato il tuo zip, dovrai configurare il nome, il file principale o il runtime environment e altre impostazioni per il tuo progetto.
Se stai caricando un progetto web, assicurati di selezionare “Web Publication” e di impostare un sottodominio per il tuo progetto.

3

Esegui il deploy del tuo progetto

Infine, clicca sul pulsante “Deploy” per ospitare il tuo progetto su Square Cloud.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.

4

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Nella dashboard, attendi che lo stato della tua applicazione mostri “in esecuzione” e controlla i log per eventuali errori di avvio.
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

​

Tramite 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

​

Impostare il webhook secret

• Dashboard: nella pagina di upload, apri Advanced configuration e aggiungi la variabile prima del deploy. Per un’applicazione già pubblicata, aggiungila nella sua pagina Environment Variables.
• CLI: dalla cartella del tuo progetto, impostala con squarecloud app env set e riavvia l’applicazione:

squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret
squarecloud app restart

​

Avviare i test

• Per il codice JavaScript che abbiamo creato con app.post("/topgg", ...), la route che riceverà i voti è “/topgg”. Quindi, se il tuo sito web è mysite.squareweb.app, il Webhook URL è https://mysite.squareweb.app/topgg.
• Per il codice Python che abbiamo creato con @app.route("/topgg", methods=["POST"]), la route che riceverà i voti è anch’essa “/topgg”. Quindi, il Webhook URL è lo stesso https://mysite.squareweb.app/topgg.

​

Risoluzione dei problemi

​

Prossimi passi

​

Contattaci