Recevoir les webhooks de vote Top.gg

​

Introduction

• Ce guide suppose que vous avez un bot approuvé sur top.gg et que vous utilisez Node.js ou Python pour votre projet.
• Ensuite, vous devrez créer un compte sur Square Cloud, ce que vous pouvez faire depuis la page d’inscription. Vous pouvez utiliser votre e-mail pour créer un compte.
• Enfin, vous devez disposer d’un plan actif sur votre compte. Comparez les plans disponibles et choisissez-en un selon vos besoins.

​

Configuration de l’environnement

npm init -y
npm pkg set type=module

npm install express

pip install flask waitress

​

Configuration du projet

• Choisissez le sous-domaine que votre application utilisera sur Square Cloud (le champ SUBDOMAIN de votre fichier de configuration), par exemple mysite. L’URL de votre webhook sera alors https://mysite.squareweb.app/topgg.
• Sur Top.gg, ouvrez le tableau de bord de votre projet et allez dans Webhooks.
• Collez l’URL du webhook et enregistrez. Top.gg génère alors un secret de webhook qui commence par whs_ : copiez-le et gardez-le privé. Votre code le lit depuis la variable d’environnement 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)))

​

Créer le fichier de configuration 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

​

Envoyer votre application sur Square Cloud

​

Via le tableau de bord

1

Accéder à la page d'upload

Accédez à la page d’upload et téléversez le fichier zip de votre projet.

2

Configurer votre environnement

Après avoir téléversé votre zip, vous devrez configurer le nom, le fichier principal ou l’environnement d’exécution ainsi que d’autres paramètres de votre projet.
Si vous téléversez un projet web, veillez à sélectionner « Publication Web » et à définir un sous-domaine pour votre projet.

3

Déployer votre projet

Enfin, cliquez sur le bouton « Deploy » pour héberger votre projet sur Square Cloud.
Une fois le déploiement effectué, vous pouvez suivre l’état et les logs de votre projet depuis le tableau de bord.

4

Confirmez que votre application est en ligne

Votre premier déploiement prend généralement moins d’une minute. Dans le tableau de bord, attendez que le statut de votre application affiche « en cours d’exécution » et vérifiez les logs pour détecter d’éventuelles erreurs de démarrage.
Si vous avez déployé un site web ou une API, ouvrez https://<votre-sous-domaine>.squareweb.app dans votre navigateur, vous devriez voir votre application répondre. Si vous avez déployé un bot, envoyez-lui une commande pour confirmer qu’il est en ligne.

Votre application ne démarre pas ? Consultez le guide de dépannage pour les causes les plus courantes et leurs solutions.

​

Via la 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

​

Définir le secret du webhook

• Tableau de bord : sur la page d’envoi, ouvrez Configuration avancée et ajoutez la variable avant de déployer. Pour une application déjà déployée, ajoutez-la sur sa page Variables d’environnement.
• CLI : depuis le dossier de votre projet, définissez-la avec squarecloud app env set et redémarrez l’application :

squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret
squarecloud app restart

​

Lancer les tests

• Pour le code JavaScript que nous avons créé avec app.post("/topgg", ...), la route qui recevra les votes est « /topgg ». Donc, si votre site est mysite.squareweb.app, l’URL du webhook est https://mysite.squareweb.app/topgg.
• Pour le code Python que nous avons créé avec @app.route("/topgg", methods=["POST"]), la route qui recevra les votes est également « /topgg ». Ainsi, l’URL du webhook est la même : https://mysite.squareweb.app/topgg.

​

Dépannage

​

Prochaines étapes

​

Contactez-nous