> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Cómo crear un webhook de Top.gg

# 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:

```txt
npm install @top-gg/sdk express
```

```javascript
// 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.

```python
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.