Cómo crear un webhook de Top.gg en Square Cloud

Los webhooks son fundamentales para integrar tu bot con servicios externos. En el caso de Top.gg, cada vez que un usuario vota por tu bot, su servidor envía una petición POST a tu aplicación. En Square Cloud, puedes alojar ese webhook de forma estable en el puerto 80.

1. ¿Cómo funciona la comunicación?

Cuando ocurre un voto, Top.gg actúa como el cliente y tu aplicación en Square Cloud actúa como el servidor.

1. El usuario vota en Top.gg.
2. Top.gg envía un paquete de datos (JSON) a la URL de tu aplicación.
3. Tu aplicación valida si la petición es legítima (vía Token de Autorización) y procesa el voto.

2. Implementación en JavaScript (Express)

Express es la opción más común por su simplicidad para manejar rutas HTTP. Top.gg ofrece un paquete para ayudar en esta tarea; instálalo con el comando de abajo y luego revisa el ejemplo de uso:

npm install @top-gg/sdk express

// Importe as bibliotecas
const Topgg = require("@top-gg/sdk");
const express = require("express");

// Crie a aplicação Express e a instância do webhook Top.gg
const app = express();
const webhook = new Topgg.Webhook("YOUR_AUTHORIZATION_TOKEN");

// Defina a rota para endpoint '/topgg' (requisições POST)
app.post("/webhook", webhook.listener((vote) => {
  console.log(`Voto recebido com sucesso! ID do usuário: ${vote.user}`);
}));

// Inicie o servidor na porta 80
app.listen(80);

3. Implementación en Python (Flask)

Para quien prefiere Python, Flask ofrece una solución ligera y directa.

from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def topgg_webhook():
    # Verificação do Token
    auth_header = request.headers.get('Authorization')
    topgg_token = os.getenv('TOPGG_AUTH')

    if auth_header == topgg_token:
        data = request.json
        user_id = data.get('user')
        print(f"Voto confirmado para o usuário: {user_id}")
        
        return jsonify({"status": "success"}), 200
    else:
        return jsonify({"error": "unauthorized"}), 401

if __name__ == '__main__':
    # Configuração obrigatória para Square Cloud
    app.run(host='0.0.0.0', port=80)

4. Configuración en Square Cloud

Para que el webhook funcione, debes configurar tu aplicación como un Webserver:

1. Deploy: Envía tu código (recuerda no enviar node_modules ni venv).
2. Publicar en la Web: En el menú de envío del Dashboard, activa la opción "Publicar en la Web".
3. Subdominio: Define un nombre (ej.: topgg-webhook). Tu URL final será https://topgg-webhook.squareweb.app/webhook.
4. Variables de Entorno (ENV): Añade la clave TOPGG_AUTH con el token que crearás en el sitio de Top.gg.

5. Configuración en el panel de Top.gg

1. Ve a la página de edición de tu bot en Top.gg.
2. Busca la pestaña Webhooks.
3. En el campo Webhook URL, pega la URL generada por Square Cloud (ej.: https://topgg-webhook.squareweb.app/webhook).
4. En el campo Authorization, crea una contraseña/token y guárdala (recuerda poner esa misma contraseña en la ENV de Square Cloud).
5. Haz clic en Test para enviar un voto de prueba y verificar si aparece en los logs de tu Dashboard.

6. Buenas prácticas

• Seguridad: Nunca expongas el token de autorización en tu código. Usa siempre variables de entorno.
• Logs: Mantén logs de las peticiones recibidas para poder depurar si un voto no se procesa.
• Tratamiento de errores: Responde siempre con 200 OK rápidamente. Si tu lógica de recompensa es lenta, procésala de forma asíncrona para no causar timeout en el servidor de Top.gg.

Actualizado el: 13/06/2026