Recibe webhooks de votos de Top.gg

​

Introducción

• Esta guía asume que tienes un bot aprobado en top.gg y que estás usando Node.js o Python para tu proyecto.
• A continuación, necesitarás crear una cuenta en Square Cloud, lo cual puede hacerse a través de la página de registro. Puedes usar tu correo electrónico para crear una cuenta.
• Finalmente, necesitas tener un plan activo en tu cuenta. Compara los planes disponibles y elige uno según tus necesidades.

​

Configurando el entorno

npm init -y
npm pkg set type=module

npm install express

pip install flask waitress

​

Configurando el proyecto

• Elige el subdominio que usará tu aplicación en Square Cloud (el campo SUBDOMAIN de tu archivo de configuración), por ejemplo mysite. Tu URL de webhook será entonces https://mysite.squareweb.app/topgg.
• En Top.gg, abre el dashboard de tu proyecto y ve a Webhooks.
• Pega la URL del webhook y guarda. Top.gg genera entonces un secreto de webhook que empieza con whs_: cópialo y mantenlo en privado. Tu código lo lee de la variable de entorno 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)))

​

Creando el archivo de configuración de 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

​

Subiendo tu aplicación a Square Cloud

​

A través del panel

1

Accede a la página de subida

Accede a la página de subida y sube el archivo zip de tu proyecto.

2

Configura tu entorno

Después de subir tu zip, deberás configurar el nombre, el archivo principal o el entorno de ejecución y otros ajustes de tu proyecto.
Si estás subiendo un proyecto web, asegúrate de seleccionar “Publicación Web” y de definir un subdominio para tu proyecto.

3

Despliega tu proyecto

Por último, haz clic en el botón “Deploy” para alojar tu proyecto en Square Cloud.
Tras el despliegue, puedes monitorear el estado y los logs de tu proyecto desde el panel.

4

Confirma que tu aplicación esté en vivo

Tu primer despliegue suele tardar menos de un minuto. En el dashboard, espera a que el estado de tu aplicación muestre “running” y revisa los logs por si hay errores de inicio.
Si desplegaste un sitio web o una API, abre https://<tu-subdominio>.squareweb.app en tu navegador: deberías ver tu aplicación respondiendo. Si desplegaste un bot, envíale un comando para confirmar que esté online.

¿La aplicación no inicia? Consulta la guía de solución de problemas para ver las causas y soluciones más comunes.

​

A través de 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

​

Configurando el secreto del webhook

• Dashboard: en la página de subida, abre Configuración avanzada y añade la variable antes del deploy. Para una aplicación que ya está en línea, añádela en su página Variables de entorno.
• CLI: desde la carpeta de tu proyecto, defínela con squarecloud app env set y reinicia la aplicación:

squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret
squarecloud app restart

​

Iniciando las pruebas

• Para el código JavaScript que creamos con app.post("/topgg", ...), la ruta que recibirá los votos es “/topgg”. Entonces, si tu sitio web es mysite.squareweb.app, la Webhook URL es https://mysite.squareweb.app/topgg.
• Para el código Python que creamos con @app.route("/topgg", methods=["POST"]), la ruta que recibirá los votos también es “/topgg”. Entonces, la Webhook URL es la misma https://mysite.squareweb.app/topgg.

​

Solución de problemas

​

Próximos pasos

​

Contáctanos