> ## 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).

# How to create a Top.gg webhook

# How to Create a Top.gg Webhook on Square Cloud

Webhooks are fundamental for integrating your bot with external services. In the case of Top.gg, whenever a user votes for your bot, their server sends a `POST` request to your application. On Square Cloud, you can host this webhook stably on port 80.

---

## 1. How Does the Communication Work?

When a vote occurs, Top.gg acts as the client and your application on Square Cloud acts as the server.

1.  **User** votes on Top.gg.
2.  **Top.gg** sends a data packet (JSON) to your application's URL.
3.  **Your Application** validates if the request is legitimate (via Authorization Token) and processes the vote.

---

## 2. Implementation in JavaScript (Express)

Express is the most common choice due to its simplicity in handling HTTP routes. Top.gg offers a package to assist with this task; install it with the command below and then check out the usage example: 

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

```javascript
// Import libraries
const Topgg = require("@top-gg/sdk");
const express = require("express");

// Create the Express application and the Top.gg webhook instance
const app = express();
const webhook = new Topgg.Webhook("YOUR_AUTHORIZATION_TOKEN");

// Define the route for the '/webhook' endpoint (POST requests)
app.post("/webhook", webhook.listener((vote) => {
  console.log(`Vote successfully received! User ID: ${vote.user}`);
}));

// Start the server on port 80
app.listen(80);
```

---

## 3. Implementation in Python (Flask)

For those who prefer Python, Flask offers a lightweight and straightforward solution.

```python
from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def topgg_webhook():
    # Token Verification
    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"Vote confirmed for user: {user_id}")
        
        return jsonify({"status": "success"}), 200
    else:
        return jsonify({"error": "unauthorized"}), 401

if __name__ == '__main__':
    # Required configuration for Square Cloud
    app.run(host='0.0.0.0', port=80)
```

---

## 4. Configuration on Square Cloud

For the webhook to work, you must configure your application as a Webserver:

1.  **Deployment:** Upload your code (remember not to send `node_modules` or `venv`).
2.  **Publish to Web:** In the Dashboard submission menu, enable the **"Publish to Web"** option.
3.  **Subdomain:** Define a name (e.g., `topgg-webhook`). Your final URL will be `https://topgg-webhook.squareweb.app/webhook`.
4.  **Environment Variables (ENV):** Add the `TOPGG_AUTH` key with the token you will create on the Top.gg website.

---

## 5. Configuration on the Top.gg Panel

1.  Go to your bot's edit page on **Top.gg**.
2.  Look for the **Webhooks** tab.
3.  In the **Webhook URL** field, paste the URL generated by Square Cloud (e.g., `https://topgg-webhook.squareweb.app/webhook`).
4.  In the **Authorization** field, create a password/token and save it (remember to put this same password in the Square Cloud ENV).
5.  Click **Test** to send a test vote and check if it appears in your Dashboard logs.

---

## 6. Best Practices

* **Security:** Never expose the authorization token in your code. Always use environment variables.
* **Logs:** Keep logs of received requests to be able to debug if a vote is not processed.
* **Error Handling:** Always respond with `200 OK` quickly. If your reward logic is time-consuming, process it asynchronously to avoid causing a timeout on the Top.gg server.
```