Introdução
- Este guia supõe que você tenha um bot aprovado no top.gg e esteja usando Node.js ou Python em seu projeto.
- Em seguida, crie uma conta na Square Cloud através da página de cadastro. Você pode usar seu e-mail para se registrar.
- Por fim, é necessário ter um plano ativo na sua conta. Compare os planos disponíveis e escolha um conforme a sua necessidade.
Configurando o ambiente
- Node.js
- Python
- Antes de começar, verifique se você tem o Node.js e o npm instalados em seu sistema. Caso contrário, faça o download no site oficial do Node.js.
- Inicie um novo projeto Node.js e habilite a sintaxe
importcom os comandos:
Terminal
- Instale o Express:
Terminal
Configurando o projeto
1. Obtenha o secret do webhook:- Escolha o subdomínio que sua aplicação vai usar na Square Cloud (o campo
SUBDOMAINdo seu arquivo de configuração), por exemplomysite. A URL do seu webhook será entãohttps://mysite.squareweb.app/topgg. - No Top.gg, abra o dashboard do seu projeto e vá em Webhooks.
- Cole a URL do webhook e salve. O Top.gg então gera um secret de webhook que começa com
whs_: copie-o e mantenha-o privado. Seu código o lê da variável de ambienteTOPGG_WEBHOOK_SECRET.
O Top.gg assina cada requisição com o header
x-topgg-signature, no formato t=<timestamp>,v1=<signature>, em que a assinatura é um HMAC SHA-256 de <timestamp>.<raw body> gerado com o seu secret. O código abaixo recalcula essa assinatura e rejeita qualquer requisição que não bata, assim ninguém mais consegue enviar votos falsos para a sua URL. Veja a documentação de webhooks do Top.gg para mais detalhes.Este guia usa os webhooks v1 do Top.gg. O webhook legado v0, que envia uma senha no header
Authorization com um payload diferente, não é abordado aqui.- Node.js
- Python
O exemplo verifica a assinatura com o módulo nativo
crypto do Node, então nenhum pacote do Top.gg é necessário. A classe Webhook do @top-gg/sdk 4.0.0 não é usada: nos nossos testes, o listener dela respondia entregas válidas com um erro de timeout, o que faz o Top.gg reenviá-las.index.js
Criando o arquivo de configuração da Square Cloud
Crie um arquivosquarecloud.app na pasta do seu projeto. Defina SUBDOMAIN com o subdomínio que você escolheu no passo 1:
SUBDOMAIN publica o listener em https://mysite.squareweb.app, e aplicações web precisam de pelo menos MEMORY=512. O código escuta na porta da variável de ambiente PORT, que a Square Cloud define como 80, e no host 0.0.0.0.
Aprenda como: criar o arquivo de configuração para a Square Cloud.
O arquivo
squarecloud.app é usado para definir nome, descrição, versão, arquivo principal e outras configurações da sua aplicação.Enviando sua aplicação para a Square Cloud
Após seguir todos os passos, a pasta do seu projeto deve conter o seu código, o arquivo de dependências (package.json ou requirements.txt) e o arquivo de configuração. Para enviar pelo dashboard, coloque-os em um arquivo .zip.
Se a sua aplicação é um projeto Node.js, dê uma olhada no nosso artigo sobre Node.js.
Se a sua aplicação é um projeto Python, dê uma olhada no nosso artigo sobre Python.
Via dashboard
1
Acesse a página de upload
Acesse a página de upload e envie seu arquivo zip.
2
Configure seu ambiente
Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.
3
Faça o deploy do projeto
Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud.
Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

4
Confirme que seu app está no ar
Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra
Se você fez deploy de um site ou API, abra
https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Via CLI
Para usar esse método, seu projeto precisa de um arquivo de configuração chamadosquarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.
Guia do arquivo de configuração
Saiba como criar o arquivo de configuração
squarecloud.app que define o ambiente da sua aplicação.1
Instale a CLI
Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:
2
Faça login
Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.
3
Envie o seu projeto
Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o Para enviar um zip que você mesmo criou, passe-o com
squarecloud.ignore lista, e faz o upload:--file:4
Confirme que seu app está no ar
Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:Se você fez deploy de um site ou API, abra
https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Definindo o secret do webhook
Adicione o seu secretwhs_ como a variável de ambiente TOPGG_WEBHOOK_SECRET da sua aplicação, de uma destas formas:
- Dashboard: na página de upload, abra Configuração avançada e adicione a variável antes do deploy. Para uma aplicação que já está no ar, adicione-a na página Variáveis de ambiente dela.
- CLI: a partir da pasta do projeto, defina-a com
squarecloud app env sete reinicie a aplicação:
401 Unauthorized. Veja Variáveis de ambiente para as outras formas de gerenciá-las.
Iniciando os testes
Se você fez tudo corretamente, abrahttps://mysite.squareweb.app/topgg no navegador (troque mysite pelo seu subdomínio). Se aparecer “Cannot GET /topgg” (Node.js) ou “Method Not Allowed” (Python), está tudo certo: a rota só aceita as requisições POST que o Top.gg envia.
-
No código JavaScript que criamos com
app.post("/topgg", ...), a rota que vai receber os votos é “/topgg”. Então, se o seu site émysite.squareweb.app, a URL do webhook éhttps://mysite.squareweb.app/topgg. -
No código Python que criamos com
@app.route("/topgg", methods=["POST"]), a rota que vai receber os votos também é “/topgg”. Então, a URL do webhook é a mesmahttps://mysite.squareweb.app/topgg.
console.log ou no print deve aparecer nos logs.

Solução de problemas
Domínio personalizado
Para usar um domínio personalizado (ex.:
meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.Requisitos mínimos de RAM
Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.
Não foi possível encontrar esse site.
Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.
Site demorou demais para responder…
O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (
80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.Próximos passos
Bot do Discord
Hospede o bot que recebe os votos.
Variáveis de ambiente
Gerencie o secret do webhook e outros segredos.
A aplicação não inicia
Corrija conflitos de porta, módulos faltando e outras falhas na inicialização.

