Top.gg-Vote-Webhooks empfangen

​

Einführung

• Diese Anleitung setzt voraus, dass du einen genehmigten Bot auf top.gg hast und für dein Projekt entweder Node.js oder Python verwendest.
• Als Nächstes musst du ein Konto bei Square Cloud erstellen, was über die Registrierungsseite möglich ist. Du kannst deine E-Mail-Adresse verwenden, um ein Konto zu erstellen.
• Schließlich musst du einen aktiven Plan in deinem Konto haben. Vergleiche die verfügbaren Pläne und wähle einen passend zu deinen Bedürfnissen.

​

Einrichtung der Umgebung

npm init -y
npm pkg set type=module

npm install express

pip install flask waitress

​

Einrichtung des Projekts

• Wähle die Subdomain, die deine Anwendung auf Square Cloud verwenden wird (das Feld SUBDOMAIN deiner Konfigurationsdatei), zum Beispiel mysite. Deine Webhook-URL lautet dann https://mysite.squareweb.app/topgg.
• Öffne auf Top.gg das Dashboard deines Projekts und gehe zu Webhooks.
• Füge die Webhook-URL ein und speichere. Top.gg erzeugt daraufhin ein Webhook-Secret, das mit whs_ beginnt: Kopiere es und halte es geheim. Dein Code liest es aus der Umgebungsvariable TOPGG_WEBHOOK_SECRET.

import crypto from "node:crypto";
import express from "express";

const app = express();
// The whs_ secret from your project's Webhooks page on Top.gg
const SECRET = process.env.TOPGG_WEBHOOK_SECRET;

function isValidSignature(rawBody, header = "") {
  // Header format: t=<unix timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
  const timestamp = Number(parts.t);
  if (!SECRET || !Buffer.isBuffer(rawBody) || !parts.v1 || !timestamp) return false;
  // Reject requests older than 5 minutes (replay protection)
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.`).update(rawBody).digest();
  const received = Buffer.from(parts.v1, "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// express.raw keeps the exact bytes Top.gg signed
app.post("/topgg", express.raw({ type: "*/*" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("x-topgg-signature"))) return res.sendStatus(401);

  const { type, data } = JSON.parse(req.body);
  // "vote.create" is a real vote, "webhook.test" comes from the Send Test button
  if (type === "vote.create" || type === "webhook.test") {
    console.log(`Vote received successfully! User ID: ${data.user.platform_id}`);
  }
  res.sendStatus(204);
});

// Square Cloud sets PORT=80 and routes your subdomain's traffic to it
const port = Number(process.env.PORT) || 80;
app.listen(port, "0.0.0.0", () => console.log(`Listening on port ${port}`));

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request
from waitress import serve

app = Flask(__name__)

# The whs_ secret from your project's Webhooks page on Top.gg
SECRET = os.environ.get("TOPGG_WEBHOOK_SECRET", "")


def is_valid_signature(raw_body: bytes, header: str) -> bool:
    # Header format: t=<unix timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = parts["t"]
        signature = parts["v1"]
        age = abs(time.time() - int(timestamp))
    except (KeyError, ValueError):
        return False
    if age > 300:  # reject requests older than 5 minutes (replay protection)
        return False
    message = timestamp.encode() + b"." + raw_body
    expected = hmac.new(SECRET.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), signature.encode())


# Top.gg sends signed POST requests to this route
@app.route("/topgg", methods=["POST"])
def topgg_webhook():
    raw_body = request.get_data()
    if not SECRET or not is_valid_signature(raw_body, request.headers.get("x-topgg-signature", "")):
        abort(401)

    payload = json.loads(raw_body)
    # "vote.create" is a real vote, "webhook.test" comes from the Send Test button
    if payload["type"] in ("vote.create", "webhook.test"):
        print(f'Vote received successfully! User ID: {payload["data"]["user"]["platform_id"]}')
    return "", 204


if __name__ == "__main__":
    # Square Cloud sets PORT=80 and routes your subdomain's traffic to it
    serve(app, host="0.0.0.0", port=int(os.environ.get("PORT", 80)))

​

Erstellen der squarecloud-Konfigurationsdatei

DISPLAY_NAME=Top.gg Webhook
MAIN=index.js
MEMORY=512
VERSION=recommended
SUBDOMAIN=mysite

DISPLAY_NAME=Top.gg Webhook
MAIN=app.py
MEMORY=512
VERSION=recommended
SUBDOMAIN=mysite

​

Deine Anwendung auf Square Cloud hochladen

​

Über das Dashboard

1

Upload-Seite aufrufen

Rufe die Upload-Seite auf und lade die ZIP-Datei deines Projekts hoch.

2

Umgebung konfigurieren

Nachdem du deine ZIP-Datei hochgeladen hast, musst du den Namen, die Hauptdatei oder Runtime-Umgebung und weitere Einstellungen für dein Projekt konfigurieren.
Wenn du ein Web-Projekt hochlädst, achte darauf, “Web Publication” auszuwählen und deinem Projekt eine Subdomain zuzuweisen.

3

Projekt bereitstellen

Klicke abschließend auf die Schaltfläche “Deploy”, um dein Projekt auf Square Cloud zu hosten.
Nach dem Deploy kannst du den Status und die Logs deines Projekts über das Dashboard überwachen.

4

Bestätige, dass deine App live ist

Dein erstes Deploy dauert in der Regel weniger als eine Minute. Warte im Dashboard, bis der Status deiner Anwendung als “running” angezeigt wird, und prüfe die Logs auf Startfehler.
Wenn du eine Website oder API bereitgestellt hast, öffne https://<deine-subdomain>.squareweb.app in deinem Browser: du solltest sehen, dass deine Anwendung reagiert. Wenn du einen Bot bereitgestellt hast, sende ihm einen Befehl, um zu bestätigen, dass er online ist.

App startet nicht? Im Leitfaden zur Fehlerbehebung findest du die häufigsten Ursachen und Lösungen.

​

Über die CLI

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

squarecloud auth login

squarecloud upload

squarecloud upload --file <path/to/zip>

squarecloud app status
squarecloud app logs

​

Das Webhook-Secret festlegen

• Dashboard: Öffne auf der Upload-Seite Erweiterte Konfiguration und füge die Variable vor dem Deploy hinzu. Bei einer bereits deployten Anwendung fügst du sie auf ihrer Seite Umgebungsvariablen hinzu.
• CLI: Setze sie in deinem Projektordner mit squarecloud app env set und starte die Anwendung neu:

squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret
squarecloud app restart

​

Tests starten

• Für den JavaScript-Code, den wir mit app.post("/topgg", ...) erstellt haben, ist die Route, die die Votes empfängt, “/topgg”. Wenn deine Website also mysite.squareweb.app ist, lautet die Webhook-URL https://mysite.squareweb.app/topgg.
• Für den Python-Code, den wir mit @app.route("/topgg", methods=["POST"]) erstellt haben, ist die Route, die die Votes empfängt, ebenfalls “/topgg”. Die Webhook-URL ist also dieselbe: https://mysite.squareweb.app/topgg.

​

Fehlerbehebung

​

Nächste Schritte

​

Kontaktiere uns