Como Criar um Webhook do Top.gg na Square Cloud

Os webhooks são fundamentais para integrar seu bot com serviços externos. No caso do Top.gg, sempre que um usuário vota no seu bot, o servidor deles envia uma requisição POST para a sua aplicação. Na Square Cloud, você pode hospedar esse webhook de forma estável na porta 80.

1. Como Funciona a Comunicação?

Quando um voto ocorre, o Top.gg atua como o cliente e sua aplicação na Square Cloud atua como o servidor.

1. Usuário vota no Top.gg.
2. Top.gg envia um pacote de dados (JSON) para a URL da sua aplicação.
3. Sua Aplicação valida se a requisição é legítima (via Token de Autorização) e processa o voto.

2. Implementação em JavaScript (Express)

O Express é a escolha mais comum pela sua simplicidade em lidar com rotas HTTP. A Top.gg oferece um pacote para auxiliar nessa tarefa, instale-o com o comando abaixo e depois confira o exemplo 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. Implementação em Python (Flask)

Para quem prefere Python, o Flask oferece uma solução leve e direta.

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. Configuração na Square Cloud

Para que o webhook funcione, você deve configurar sua aplicação como um Webserver:

1. Deploy: Envie seu código (lembre-se de não enviar a node_modules ou venv).
2. Publicar na Web: No menu de envio do Dashboard, ative a opção "Publicar na Web".
3. Subdomínio: Defina um nome (ex: topgg-webhook). Sua URL final será https://topgg-webhook.squareweb.app/webhook.
4. Variáveis de Ambiente (ENV): Adicione a chave TOPGG_AUTH com o token que você criará no site do Top.gg.

5. Configuração no Painel do Top.gg

1. Vá até a página de edição do seu bot no Top.gg.
2. Procure a aba Webhooks.
3. No campo Webhook URL, cole a URL gerada pela Square Cloud (ex: https://topgg-webhook.squareweb.app/webhook).
4. No campo Authorization, crie uma senha/token e salve (lembre-se de colocar essa mesma senha na ENV da Square Cloud).
5. Clique em Test para enviar um voto de teste e verificar se aparece nos logs do seu Dashboard.

6. Boas Práticas

• Segurança: Nunca exponha o token de autorização no seu código. Use sempre variáveis de ambiente.
• Logs: Mantenha logs das requisições recebidas para conseguir debugar caso um voto não seja processado.
• Tratamento de Erros: Responda sempre com 200 OK rapidamente. Se sua lógica de recompensa for demorada, processe-a de forma assíncrona para não causar timeout no servidor do Top.gg.

Atualizado em: 29/04/2026