# GAMEMONITORING > Die GAMEMONITORING REST API liefert JSON-Daten zu Servern, Spielern, Beiträgen, Online-Verläufen und Stimmen. Diese Seite erklärt die Grundlagen der Integration und die erste Anfrage. Parameter und Anfragetests finden Sie auf den Endpunktseiten. - [GAMEMONITORING API](https://gamemonitoring.de/developers/docs/api.md) - [GAMEMONITORING MCP](https://gamemonitoring.de/developers/docs/mcp.md) - [Server hinzufügen](https://gamemonitoring.de/developers/docs/api/servers/__post.md) - [Server](https://gamemonitoring.de/developers/docs/api/servers/:server_id/__get.md) - [Spieler des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/players/__get.md) - [Beiträge, die den Server erwähnen](https://gamemonitoring.de/developers/docs/api/servers/:server_id/posts/__get.md) - [Spielerzahl des Servers im Zeitverlauf](https://gamemonitoring.de/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [Stimmen für den Server](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/__get.md) - [Stimmendiagramm des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [Aktivste Abstimmende des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/top/__get.md) - [Spielerzahl des Projekts im Zeitverlauf](https://gamemonitoring.de/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [Projektstimmen](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/__get.md) - [Stimmendiagramm des Projekts](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [Aktivste Abstimmende des Projekts](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/top/__get.md) - [Stimme](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__get.md) - [Stimmenverarbeitung bestätigen](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/claim/__post.md) - [Nutzerprofil](https://gamemonitoring.de/developers/docs/api/users/:id/__get.md) - [Kontoinhaberschaft bestätigen](https://gamemonitoring.de/developers/docs/api/users/verify-code/__post.md) - [Webhook](https://gamemonitoring.de/developers/docs/webhook.md) - [Belohnungen für Stimmen](https://gamemonitoring.de/developers/docs/webhook/vote.md) - [System-IP-Adressen](https://gamemonitoring.de/developers/docs/ips.md) - [OpenAPI](https://gamemonitoring.de/developers/docs/openapi.json) - [Vollständige Dokumentation](https://gamemonitoring.de/developers/docs/llms-full.txt) - [GAMEMONITORING MCP](https://api.gamemonitoring.net/mcp) --- # GAMEMONITORING API Die GAMEMONITORING REST API liefert JSON-Daten zu Servern, Spielern, Beiträgen, Online-Verläufen und Stimmen. Diese Seite erklärt die Grundlagen der Integration und die erste Anfrage. Parameter und Anfragetests finden Sie auf den Endpunktseiten. ## Basis-URL https://api.gamemonitoring.de ## Die erste Anfrage Beginnen Sie mit öffentlichen Serverdaten. Die Server-ID steht am Ende der URL der jeweiligen GAMEMONITORING-Serverseite. ```bash curl --header 'Accept: application/json' 'https://api.gamemonitoring.de/servers/1' ``` ## Endpunkt auswählen - [POST /servers — Server hinzufügen](https://gamemonitoring.de/developers/docs/api/servers/__post.md) - [GET /servers/{server_id} — Server](https://gamemonitoring.de/developers/docs/api/servers/:server_id/__get.md) - [GET /servers/{server_id}/players — Spieler des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/players/__get.md) - [GET /servers/{server_id}/posts — Beiträge, die den Server erwähnen](https://gamemonitoring.de/developers/docs/api/servers/:server_id/posts/__get.md) - [GET /servers/{server_id}/stats/players_online — Spielerzahl des Servers im Zeitverlauf](https://gamemonitoring.de/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [GET /servers/{server_id}/votes — Stimmen für den Server](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/__get.md) - [GET /servers/{server_id}/votes/chart — Stimmendiagramm des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [GET /servers/{server_id}/votes/top — Aktivste Abstimmende des Servers](https://gamemonitoring.de/developers/docs/api/servers/:server_id/votes/top/__get.md) - [GET /projects/{project_id}/stats/players_online — Spielerzahl des Projekts im Zeitverlauf](https://gamemonitoring.de/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [GET /projects/{project_id}/votes — Projektstimmen](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/__get.md) - [GET /projects/{project_id}/votes/chart — Stimmendiagramm des Projekts](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [GET /projects/{project_id}/votes/top — Aktivste Abstimmende des Projekts](https://gamemonitoring.de/developers/docs/api/projects/:project_id/votes/top/__get.md) - [GET /votes/{vote_id} — Stimme](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__get.md) - [POST /votes/{vote_id}/claim — Stimmenverarbeitung bestätigen](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/claim/__post.md) - [GET /users/{id} — Nutzerprofil](https://gamemonitoring.de/developers/docs/api/users/:id/__get.md) - [POST /users/verify-code — Kontoinhaberschaft bestätigen](https://gamemonitoring.de/developers/docs/api/users/verify-code/__post.md) ## API-Versionen Mit dem optionalen Query-Parameter v können Sie eine API-Version auswählen. Die aktuelle Version ist 1.0.0. Die Version bestimmt verfügbare Pfade, Anfragefelder und das Antwortformat. Ohne v wird die niedrigste unterstützte Version verwendet. Nach deren Abschaltung wird die nächste niedrigste unterstützte Version zum Standard. Geben Sie v an, um den Vertrag festzulegen. Ungültige, wiederholte oder nicht unterstützte Versionen liefern HTTP 400; verfügbare Versionen stehen bei nicht unterstützten Werten in error.data.supported_versions. ## Parameter übergeben IDs stehen im Anfragepfad: server_id und project_id sind numerische GAMEMONITORING-IDs; vote_id bezeichnet eine Stimme. Ersetzen Sie Parameter in geschweiften Klammern durch konkrete Werte. Filter, Zeiträume und Seitennavigation folgen nach ? in der URL. Kodieren Sie Werte mit URLSearchParams oder der entsprechenden Bibliotheksfunktion, besonders Nicknamen und Suchtexte. Senden Sie zum Hinzufügen eines Servers JSON mit Content-Type: application/json. connect ist ein öffentlicher host:port; steam_app_id ist die Steam App ID des Spiels. query ist nötig, wenn Abfrage- und Verbindungsport verschieden sind. ## Datenformat HTTP 200 enthält das Ergebnis in response: je nach Endpunkt ein Objekt, ein Array oder ein Objekt mit items. Beachten Sie das Endpunktschema; eine leere Liste ist für sich kein Fehler. Felder können null sein oder fehlen. Das unterscheidet sich von 0, false und einer leeren Zeichenfolge; behandeln Sie fehlende Daten gesondert. created_at, expires_at und last_update verwenden Unix-Zeitstempel in Sekunden. Für JavaScript Date mit 1000 multiplizieren; für Filter Date.now() durch 1000 teilen und abrunden. Behalten Sie 64-Bit-Steam-IDs als Zeichenfolgen. Eine Umwandlung in JavaScript Number kann Genauigkeit verlieren. GAMEMONITORING-Server-ID und Steam App ID des Spiels sind verschiedene Kennungen. ## Fehler und Wiederholungen Prüfen Sie HTTP-Status und error: code enthält den Status, message erläutert ihn, data liefert gegebenenfalls weitere Details. Meldungstexte hängen von der Region ab und können sich ändern; verwenden Sie sie nicht als Bedingung im Code. Beheben Sie Parameter- und Zugriffsfehler vor der Wiederholung. Behandeln Sie auch Netzwerkfehler und Proxy-Antworten, die kein JSON enthalten müssen. Die Daten stammen aus der letzten Serverabfrage und können zwischengespeichert sein. Prüfen Sie last_update, wählen Sie ein angemessenes Aktualisierungsintervall und speichern Sie Ergebnisse lokal. Häufige API-Abfragen beschleunigen die Aktualisierung des Spielservers nicht. ## Abstimmungen und Webhooks Konfigurieren Sie für neue Stimmen einen Projekt-Webhook. Prüfen Sie signature, überspringen Sie Testereignisse mit is_test=true und nutzen Sie event_id als vote_id, um die Stimme abzurufen. Prüfen Sie entity_type und entity_id und verarbeiten Sie das Ereignis anhand von event_type + event_id nur einmal. Bestätigen Sie Testereignisse mit einer 2xx-Antwort, ohne eine Belohnung zu vergeben. ## Hilfe zur Integration Geben Sie bei Fehlermeldungen HTTP-Methode, Pfad, Parameter, Zeitpunkt, HTTP-Status und den zurückgegebenen error an. Diese Angaben helfen, das Problem nachzustellen. ## OpenAPI ```json { "openapi": "3.1.1", "info": { "title": "GAMEMONITORING", "version": "1.0.0" }, "paths": { "/servers": { "post": { "operationId": "createServer", "summary": "Server hinzufügen", "description": "Fügt einen Server über seine Verbindungsadresse hinzu oder gibt den vorhandenen Server zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connect": { "type": "string", "minLength": 1, "example": "198.51.100.24:27015" }, "steam_app_id": { "type": "integer", "minimum": 0, "example": 730 }, "query": { "type": "integer", "minimum": 10, "maximum": 65535, "example": 27016 } }, "required": [ "connect", "steam_app_id" ] }, "example": { "connect": "198.51.100.24:27015", "steam_app_id": 730 } } } }, "responses": { "200": { "description": "Created or existing server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateResult" }, "example": { "response": { "connect": "198.51.100.24:27015", "game": 730, "id": 100001, "name": "Example Arena", "request": "198.51.100.24:27016", "status": true } } } } }, "400": { "description": "Missing game or address, invalid address or offline server" }, "403": { "description": "Blocked address" }, "409": { "description": "Query address is already in use" }, "503": { "description": "Server creation service is unavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}": { "get": { "operationId": "getServer", "summary": "Server", "description": "Gibt öffentliche Serverdaten zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerEnvelope" }, "example": { "response": { "steam_id": "90123456789012345", "domain": null, "id": 1, "ip": "198.51.100.24", "port": 27015, "query": 27015, "project_id": 42, "color": 0, "city": "Prague", "description": "[]", "game": 730, "boosts": 3, "last_offline": 1782751200, "last_online": 1783201200, "icon": null, "name": "Example CS2 Server", "connect": "198.51.100.24:27015", "request": "198.51.100.24:27015", "map": "de_mirage", "gamemode": "Counter-Strike 2", "version": "1.41.6.5", "numplayers": 12, "maxplayers": 64, "bots": 0, "secured": true, "private": false, "country": "CZ", "status": true, "votes": 128, "points": 2450, "add_date": 1701541119, "last_update": 1783201200, "ban_reason": null, "banned": false, "wipe": null, "official": null, "wipe_period": null, "next_wipe": null, "pve": null, "pvp": null, "list_hidden": false, "hide_address": false, "hide_query": false, "position_game": 12, "language": "en", "parked": false, "app": { "id": 2, "steam_id": 730, "name": "Counter-Strike 2", "url": "counter-strike-2" }, "mods": [ { "id": 5, "name": "Admin System" }, { "id": 14, "name": "Advertisement" }, { "id": 9, "name": "Admins" }, { "id": 3, "name": "Admin Commands" } ], "disabled_modules": [] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/players": { "get": { "operationId": "getServerPlayers", "summary": "Spieler des Servers", "description": "Gibt die Spielerliste des Servers zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "limit", "in": "query", "description": "Anzahl der Elemente von 1 bis 100, Standardwert 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server players", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayersResult" }, "example": { "response": { "items": [ { "avatar": "no.jpg", "created": 1783200000, "last_online": 1783203600, "last_session_time": 0, "name": "NovaPlayer", "user": null, "username": null } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/servers/{server_id}/posts": { "get": { "operationId": "getServerPosts", "summary": "Beiträge, die den Server erwähnen", "description": "Gibt öffentliche Beiträge mit einer sichtbaren Erwähnung des angegebenen Servers zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "before_created_at", "in": "query", "description": "Senden Sie für die nächste Seite den Wert `created_at` des letzten Beitrags als Unix-Zeit in Sekunden und seine `id` als `before_id`. Behalten Sie die übrigen Filter bei. Der Cursor funktioniert, wenn weder `sort` noch `period` gesetzt ist. Ist einer davon gesetzt, verwenden Sie `offset`.", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "before_id", "in": "query", "description": "Beitrags-ID für den Cursor", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "conversation_post_id", "in": "query", "description": "Beitrags-ID der Diskussion", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "period", "in": "query", "description": "Verwenden Sie top für den Zeitraum der besten Beiträge.", "schema": { "type": "string", "const": "top" } }, { "name": "reply_to_post_id", "in": "query", "description": "ID des übergeordneten Beitrags", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "root_only", "in": "query", "description": "Mit 1 nur Hauptbeiträge zurückgeben", "schema": { "type": "number", "const": 1 } }, { "name": "sort", "in": "query", "description": "Sortierung der Beiträge. Verwenden Sie helpful-desc für die besten Beiträge.", "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "description": "Diese Operation gibt nur öffentliche Beiträge zurück.", "schema": { "type": "string", "const": "public" } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "Anzahl der Elemente von 1 bis 100, Standardwert 20", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 120, "example": "admin" } } ], "responses": { "200": { "description": "Public posts mentioning the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPostsResult" }, "example": { "response": [ { "id": 1001, "comment": "Great server! Thanks to the admin team.", "conversation_post_id": null, "language": "en", "moderation_needed": false, "replays": 0, "reply_to_post_id": null, "views": 25, "updated_at": null, "created_at": 1783200000, "translated_content": null, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user" }, "images": [], "mentions": [ { "type": "server", "meta": { "game": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "icon": null, "id": 1, "name": "Example CS2 Server" } } ], "reactions": [], "replays_items": [], "replays_items_count": 0 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Server not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/stats/players_online": { "get": { "operationId": "getServerPlayerStats", "summary": "Spielerzahl des Servers im Zeitverlauf", "description": "Gibt ein Diagramm der Spielerzahl mit Minimum, Durchschnitt und Maximum je Intervall zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "Statistikzeitraum: day, week oder month; Standardwert month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "maps": [ "de_mirage" ], "max_players": 16, "min_players": 8, "x": 1783200000, "y": 16 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes": { "get": { "operationId": "getServerVotes", "summary": "Stimmen für den Server", "description": "Gibt die Stimmen für den angegebenen Server zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "Benutzer-ID", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "server", "expires_at": 1783243200, "id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "nickname": "NovaPlayer", "server": { "app": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "game": 730, "icon": null, "id": 42, "name": "Example CS2 Server" }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes/chart": { "get": { "operationId": "getServerVoteChart", "summary": "Stimmendiagramm des Servers", "description": "Gibt die Anzahl der Stimmen pro Tag zurück.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/servers/{server_id}/votes/top": { "get": { "operationId": "getServerTopVoters", "summary": "Aktivste Abstimmende des Servers", "description": "Gibt Benutzer mit den meisten Stimmen zurück.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1783243200, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/projects/{project_id}/stats/players_online": { "get": { "operationId": "getProjectPlayerStats", "summary": "Spielerzahl des Projekts im Zeitverlauf", "description": "Gibt das Minimum, den Durchschnitt und das Maximum der gleichzeitigen Spielerzahl aller Projektserver je Intervall zurück.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "Statistikzeitraum: day, week oder month; Standardwert month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Combined project player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "max_players": 16, "min_players": 8, "x": 1783200000 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes": { "get": { "operationId": "getProjectVotes", "summary": "Projektstimmen", "description": "Gibt die Stimmen für das Projekt zurück. Ohne Authentifizierung sind nur öffentliche Projekte zugänglich.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "Benutzer-ID", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "project", "expires_at": 1785792000, "id": "7206f073-2f18-4660-91b8-bd947fbc4be2", "nickname": "NovaPlayer", "project": { "id": 42 }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/projects/{project_id}/votes/chart": { "get": { "operationId": "getProjectVoteChart", "summary": "Stimmendiagramm des Projekts", "description": "Gibt die täglichen Stimmenzahlen des Projekts zurück. Ohne Authentifizierung sind nur öffentliche Projekte zugänglich.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes/top": { "get": { "operationId": "getProjectTopVoters", "summary": "Aktivste Abstimmende des Projekts", "description": "Gibt Nutzer mit den meisten Stimmen für das Projekt zurück. Ohne Authentifizierung sind nur öffentliche Projekte zugänglich.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1785792000, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/votes/{vote_id}": { "get": { "operationId": "getVote", "summary": "Stimme", "description": "Gibt die Details einer Stimme anhand ihrer ID zurück.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Vote details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteDetailsEnvelope" }, "example": { "response": { "created_at": 1783200000, "expires_at": 1783243200, "id": "6f59a4a8-2f0f-4d96-a50a-9d7a21f4b812", "entity_id": 100001, "entity_type": "server", "nickname": "NovaPlayer", "server": { "app": { "id": 2400, "name": "Example Shooter", "steam_id": 111111, "url": "example-shooter" }, "game": 111111, "icon": null, "id": 100001, "name": "Example Arena" }, "user": { "avatar": "8f14e45f-e9a1-4f4d-a9f3-6d7b0d4a2c18.webp", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [ { "id": "100000000000000001", "name": "demo_user", "type": "discord", "url": "https://discord.com/users/100000000000000001" }, { "id": "76561198000000001", "name": "NovaPlayer", "type": "steam", "url": "https://steamcommunity.com/profiles/76561198000000001" } ] }, "claimed_at": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "security": [] } }, "/votes/{vote_id}/claim": { "post": { "operationId": "claimVote", "summary": "Stimmenverarbeitung bestätigen", "description": "Markiert eine Stimme als verarbeitet. Für Eigentümer des Servers oder Projekts verfügbar.", "security": [ { "AccountAPIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteClaimResult" }, "example": { "response": { "success": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing, invalid, expired or revoked credential." }, "403": { "description": "Missing API key scope, restricted account or entity ownership." }, "404": { "description": "Unknown vote or invalid entity association." }, "429": { "description": "Account claim quota exceeded: 12 000 per minute. Honor Retry-After." } } } }, "/users/{id}": { "get": { "operationId": "getPublicUser", "summary": "Nutzerprofil", "description": "Gibt die Daten des Nutzerprofils zurück.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "id", "in": "path", "required": true, "description": "Konto-ID.", "schema": { "type": "string", "format": "uuid", "example": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } ], "responses": { "200": { "description": "User profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResult" }, "example": { "response": { "avatar": "447f9470-325b-4e0a-ada0-f4f1659ef805.png", "id": 1, "username": "GAMEMONITORING", "banner": "469ebf64-206c-4374-a742-7730ea227f95.webp", "connections": [ { "account_id": "76561197960287930", "account_level": 1, "id": 220354, "name": "Rabscuttle", "platform": { "icon": null, "id": 3, "name": "Steam", "url": "steam" } } ], "created": 1435235037, "last_online": 1793734264, "uuid": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "User not found." } } } }, "/users/verify-code": { "post": { "operationId": "verifyUserCode", "summary": "Kontoinhaberschaft bestätigen", "description": "Um die Inhaberschaft eines GAMEMONITORING-Kontos zu bestätigen, ruft der Nutzer unter „[Integration](/settings/integration)“ einen Code ab. Der Code ist ab der Ausgabe 5 Minuten gültig. Bei erfolgreicher Prüfung gibt die API die ID des Kontos zurück, für das der Code ausgestellt wurde, und markiert den Code als verwendet.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Einmaliger Kontobestätigungscode. Groß- und Kleinschreibung spielen keine Rolle.", "pattern": "^\\s*[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}(?:-[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}){2}\\s*$", "example": "7KMD-P9RX-3WHT" } } } } } }, "responses": { "200": { "description": "The stable GAMEMONITORING account ID.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "response" ], "properties": { "response": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } }, "example": { "response": { "id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "description": "Invalid request or code format." }, "404": { "description": "Unknown, expired or already redeemed code." }, "429": { "description": "Too many requests." }, "503": { "description": "A required service is temporarily unavailable." } } } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP-Statuscode." }, "message": { "type": "string", "description": "Fehlermeldung in der API-Sprache. Der Text kann variieren; verwenden Sie den Statuscode zur Fehlerbehandlung." }, "data": { "description": "Zusätzliche Fehlerdetails, falls verfügbar." } } } } }, "Server": { "type": "object", "properties": { "add_date": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "app": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "steam_id": { "description": "Steam App ID of the game. Use this as game_steam_id when searching servers.", "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ] }, "url": { "type": "string" } }, "additionalProperties": {} }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connect": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hide_address": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "hide_query": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "icon": { "type": [ "string", "null" ] }, "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "ip": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "last_update": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "map": { "type": [ "string", "null" ] }, "maxplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] }, "numplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "official": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "points": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "port": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "private": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pve": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pvp": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "request": { "type": [ "string", "null" ] }, "secured": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "steam_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ], "description": "Speichern Sie Zeichenfolgen-IDs als Zeichenfolgen, um Präzisionsverluste zu vermeiden." }, "version": { "type": [ "string", "null" ] }, "votes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "ban_reason": { "type": [ "string", "null" ] }, "banned": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "boosts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bots": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "city": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Serverbeschreibung als JSON-kodierte Blockliste." }, "disabled_modules": { "type": "array", "items": { "type": "string" } }, "gamemode": { "type": [ "string", "null" ] }, "hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "last_offline": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "last_online": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "list_hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "map_url": { "type": [ "string", "null" ] }, "mods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} } }, "next_wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix-Zeitstempel in Sekunden (UTC)." }, "parked": { "type": "boolean" }, "position_game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe_period": { "type": [ "string", "null" ] } }, "required": [ "id", "parked" ], "additionalProperties": {} }, "ServerEnvelope": { "type": "object", "required": [ "response" ], "properties": { "response": { "$ref": "#/components/schemas/Server", "description": "Erfolgreiche Antworten enthalten das Ergebnis in response. Listen können Arrays oder Objekte mit items sein; siehe Schema dieser Operation." } } }, "UserProfileResult": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "id", "uuid", "username", "avatar", "banner", "created", "last_online" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "Numeric profile ID." }, "uuid": { "type": "string", "format": "uuid", "description": "Account ID." }, "username": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "banner": { "type": [ "string", "null" ] }, "created": { "type": [ "integer", "null" ] }, "last_online": { "type": [ "integer", "null" ] }, "connections": { "type": "array", "items": { "type": "object", "required": [ "id", "account_id", "account_level", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "account_id": { "type": "string" }, "account_level": { "type": [ "number", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "object", "null" ], "required": [ "id", "name", "icon", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } } } } } } } } }, "ServerCreateResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "connect": { "type": [ "string", "null" ] }, "game": { "type": [ "integer", "null" ] }, "id": { "type": "integer", "minimum": 1 }, "name": { "type": [ "string", "null" ] }, "request": { "type": [ "string", "null" ] }, "status": { "type": [ "boolean", "null" ] } }, "required": [ "connect", "game", "id", "name", "request", "status" ] } }, "required": [ "response" ] }, "ServerPlayersResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "description": "Wenn die Sitzungshistorie keine Spieler liefert, enthält `items` die vollständige Spielerliste der letzten Serverabfrage, sofern sie verfügbar ist.", "type": "array", "items": { "type": "object", "properties": { "avatar": { "type": "string" }, "created": { "type": [ "number", "string", "null" ] }, "last_online": { "type": [ "number", "string", "null" ] }, "last_session_time": { "type": "number" }, "name": { "type": [ "number", "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "username": { "type": [ "string", "null" ] } }, "required": [ "avatar", "last_session_time", "username" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ServerPostsResult": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "response" ] }, "ServerPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "maps": { "type": "array", "items": { "type": "string" } }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "avg_players", "date", "maps", "max_players", "min_players", "x", "y" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ProjectPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" } }, "required": [ "avg_players", "date", "max_players", "min_players", "x" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "VoteDetailsEnvelope": { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/VoteDetails" } } }, "VoteDetails": { "type": "object", "properties": { "id": { "type": "string", "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" }, "entity_id": { "type": "number", "description": "ID of the entity that received the vote.", "example": 1 }, "entity_type": { "type": "string", "description": "Type of the entity that received the vote.", "enum": [ "server", "project" ], "example": "server" }, "nickname": { "type": [ "string", "null" ], "example": "PlayerName" }, "created_at": { "type": "number", "example": 1710000000 }, "expires_at": { "type": "number", "example": 1710086400 }, "server": { "type": [ "object", "null" ], "description": "Present for `server` votes.", "properties": { "id": { "type": [ "number", "string", "null" ], "example": 1 }, "name": { "type": [ "string", "null" ], "example": "Public Server" }, "icon": { "type": [ "string", "null" ] }, "game": { "type": [ "number", "null" ], "example": 730 } } }, "project": { "type": [ "object", "null" ], "description": "Present for `project` votes.", "properties": { "id": { "type": "number", "example": 1 } } }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "number", "string", "null" ] }, "uuid": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] } } }, "webhook": { "type": [ "object", "null" ], "description": "Present only when the requester can view webhook delivery details.", "properties": { "attempted_at": { "type": [ "number", "null" ] }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": [ "string", "null" ], "enum": [ "server.vote", "project.vote", null ], "example": "project.vote" }, "is_test": { "type": [ "boolean", "null" ] }, "request_body": { "type": [ "object", "null" ] }, "response_body": {}, "response_code": { "type": [ "number", "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "delivered", "failed", "no_result", "pending", null ] }, "url": { "type": [ "string", "null" ] } } }, "claimed_at": { "type": [ "integer", "null" ], "description": "Processing acknowledgement time in Unix seconds; null means unclaimed.", "example": null } } }, "VoteClaimResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } }, "required": [ "response" ] } }, "parameters": { "ApiVersion": { "name": "v", "in": "query", "required": false, "description": "API-Version. Ohne v wird die niedrigste unterstützte Version verwendet. Mit v=1.0.0 bleibt der dokumentierte Vertrag festgelegt. Ungültige, wiederholte oder nicht unterstützte Werte liefern HTTP 400.", "schema": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", "const": "1.0.0" } }, "created": { "name": "created", "in": "query", "description": "Filtert nach dem exakten Erstellungszeitpunkt in Unix-Sekunden. Ohne Datumsfilter umfasst die Abfrage alle gespeicherten Stimmen.", "schema": { "type": "integer", "example": 1800000000 } }, "created__gt": { "name": "created__gt", "in": "query", "description": "Erstellungszeit, Unixzeit in Sekunden >", "schema": { "type": "integer", "example": 1800000000 } }, "created__gte": { "name": "created__gte", "in": "query", "description": "Erstellungszeit, Unixzeit in Sekunden ≥", "schema": { "type": "integer", "example": 1800000000 } }, "created__lt": { "name": "created__lt", "in": "query", "description": "Erstellungszeit, Unixzeit in Sekunden <", "schema": { "type": "integer", "example": 1800000000 } }, "created__lte": { "name": "created__lte", "in": "query", "description": "Erstellungszeit, Unixzeit in Sekunden ≤", "schema": { "type": "integer", "example": 1800000000 } }, "expire": { "name": "expire", "in": "query", "description": "Ablaufzeit, Unixzeit in Sekunden", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gt": { "name": "expire__gt", "in": "query", "description": "Ablaufzeit, Unixzeit in Sekunden >", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gte": { "name": "expire__gte", "in": "query", "description": "Ablaufzeit, Unixzeit in Sekunden ≥", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lt": { "name": "expire__lt", "in": "query", "description": "Ablaufzeit, Unixzeit in Sekunden <", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lte": { "name": "expire__lte", "in": "query", "description": "Ablaufzeit, Unixzeit in Sekunden ≤", "schema": { "type": "integer", "example": 1800000000 } }, "claimed": { "name": "claimed", "in": "query", "description": "Verarbeitung: 0 unverarbeitet, 1 verarbeitet; standardmäßig alle", "schema": { "type": "integer", "enum": [ 0, 1 ], "example": 0 } }, "limit": { "name": "limit", "in": "query", "description": "Anzahl der Elemente von 1 bis 1000, Standardwert 100", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 } }, "offset": { "name": "offset", "in": "query", "description": "Anzahl der zu überspringenden Elemente ab 0, Standardwert 0", "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 0 } }, "order": { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "asc" } }, "sort": { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created", "expire" ], "default": "created", "example": "created" } }, "nickname": { "name": "nickname", "in": "query", "description": "Suche nach Teilen des Nicknamens der abstimmenden Person, 3 bis 255 Zeichen", "schema": { "type": "string", "minLength": 3, "maxLength": 255, "example": "Player" } }, "server_id": { "name": "server_id", "in": "query", "schema": { "type": "integer", "example": 42 } }, "entity_type": { "name": "entity_type", "in": "query", "schema": { "type": "string", "enum": [ "server", "project" ], "example": "server" } }, "webhook_status": { "name": "webhook_status", "in": "query", "schema": { "type": "string", "enum": [ "delivered", "failed", "no_result", "pending" ], "example": "failed" } }, "period": { "name": "period", "in": "query", "description": "Zeitraum nach Erstellungszeit der Stimme, standardmäßig die gesamte gespeicherte Historie", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "example": "30d" } } }, "securitySchemes": { "AccountAPIKey": { "type": "http", "scheme": "bearer", "description": "Account API key: 43 base64url characters without a prefix. Claim requires votes:claim scope plus current ownership. Send only in Authorization: Bearer ." } }, "responses": { "BadRequest": { "description": "Ungültige Parameter oder JSON-Daten. Prüfen Sie Typen, Pflichtfelder und zulässige Werte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 400, "message": "Invalid request parameters." } } } } }, "Forbidden": { "description": "Zugriff verweigert: Die Adresse ist gesperrt oder das Projekt ist nicht öffentlich.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 403, "message": "Access denied." } } } } }, "ServiceUnavailable": { "description": "Der Dienst ist vorübergehend nicht verfügbar. Versuchen Sie es später erneut.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 503, "message": "Service temporarily unavailable." } } } } }, "QueryTimeout": { "description": "Die Anfrage hat das Zeitlimit überschritten. Versuchen Sie es später oder grenzen Sie die Anfrage ein.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 504, "message": "Query timed out." } } } } }, "NotFound": { "description": "Die angeforderte Ressource existiert nicht.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 404, "message": "Resource not found." } } } } }, "UnexpectedError": { "description": "Unerwarteter Serverfehler. Das Objekt error enthält den tatsächlichen Statuscode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 500, "message": "Internal server error." } } } } } } }, "servers": [ { "url": "https://api.gamemonitoring.de" } ] } ``` https://gamemonitoring.de/developers/docs/api.md --- # GAMEMONITORING MCP MCP (Model Context Protocol) gibt Agenten Zugriff auf Spiele, Server, Online-Status und Spielerzahlen von GAMEMONITORING. Alle Werkzeuge bieten Lesezugriff. Der öffentliche Zugang ist ohne Konto oder API-Schlüssel möglich. ## Agent verbinden Wähle bei manueller Einrichtung Streamable HTTP und füge die URL ein. Für Cursor und VS Code gibt es eine direkte Installation. Für Kommandozeilen-Clients stehen Befehle zum Kopieren bereit. ```text https://api.gamemonitoring.net/mcp ``` ### Codex ```bash codex mcp add gamemonitoring --url 'https://api.gamemonitoring.net/mcp' ``` ### Claude Code ```bash claude mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### Gemini CLI ```bash gemini mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### MCP JSON ```json { "mcpServers": { "gamemonitoring": { "url": "https://api.gamemonitoring.net/mcp" } } } ``` ### Beispielanfrage an einen Agenten ```text Finde mit GAMEMONITORING die drei Rust-Server mit den meisten Spielern online. Zeige für jeden Server die Adresse und die Spielerzahl. ``` ## MCP-Werkzeuge Beginne mit search_games. Verwende die zurückgegebene steam_id als game_steam_id, um Server zu suchen, zu filtern oder zu zählen. Für Serverdetails verwende die GAMEMONITORING-Server-ID aus search_servers. ### search_games Sucht Spiele nach Name, Slug oder Steam App ID. Liefert steam_id, Name, Slug sowie Server- und Spielerzahlen. ```json { "name": "Rust", "limit": 1 } ``` ### get_server_filters Listet Karten, Versionen, Länder, Sprachen, Spielmodi und andere Filter auf. Übergib game_steam_id für ein bestimmtes Spiel oder ein leeres Objekt für allgemeine Filter. ```json { "game_steam_id": 252490 } ``` ### search_servers Sucht Server nach Spiel und Filtern. Unterstützt Sortierung, limit von 1 bis 100 und offset. Gib das Spiel an, um die Suche einzugrenzen. ```json { "game_steam_id": 252490, "status": "online", "sort": "numplayers", "limit": 3 } ``` ### get_server Liefert öffentliche Details und den aktuellen Status zur numerischen server_id. ```json { "server_id": 1 } ``` ### get_server_list_metadata Zählt alle passenden Server, Online-Server und Spieler online mit denselben Filtern wie die Serversuche. ```json { "game_steam_id": 252490, "status": "online" } ``` ## Datenformat Bei erfolgreichem tools/call enthält result.structuredContent die Daten. result.content enthält eine Textdarstellung und einen Link zur zugrunde liegenden REST-Anfrage. Protokollfehler stehen im Feld error auf oberster Ebene. Bei einem Werkzeugfehler ist result.isError auch bei HTTP 200 gleich true. Falls vorhanden, stehen Details in result.structuredContent.error. Grenze die Suche bei einer Zeitüberschreitung nach Spiel oder anderen Filtern ein. https://gamemonitoring.de/developers/docs/mcp.md --- # Webhook {#webhook} Webhook sendet ein GAMEMONITORING-Ereignis nach einer Aktion auf der Plattform an Ihr System. Es ist eine normale `POST`-Anfrage mit JSON-Body, damit eine Website, ein Panel oder ein Spielservice automatisch reagieren kann. Wenn Sie Belohnungen für Stimmen einrichten, verbinden Sie zuerst den Webhook nach dieser Anleitung und nutzen danach den eigenen Ablauf: [Belohnungen für Stimmen](https://gamemonitoring.de/developers/docs/webhook/vote#flow). ## Verbindung {#connect} Diese Einstellung verbindet ein GAMEMONITORING-Projekt mit Ihrem Handler und stellt einen Signatur-Token zur Prüfung eingehender Anfragen bereit. 1. Öffnen Sie [Meine Projekte](https://gamemonitoring.de/projects/my), erstellen Sie ein Projekt oder wählen Sie ein bestehendes aus und gehen Sie dann zu den Webhook-Einstellungen. 2. Erstellen Sie einen öffentlichen HTTPS-Endpunkt, der `POST` mit `Content-Type: application/json` akzeptiert und Anfragen nicht weiterleitet. 3. Tragen Sie in den Webhook-Einstellungen die vollständige Handler-URL ein, zum Beispiel `https://panel.example.com/gamemonitoring-webhook`, und speichern Sie sie. 4. Kopieren Sie den Signatur-Token aus demselben Block und tragen Sie ihn im Handler-Skript ein. 5. Prüfen Sie im Handler `signature`, verarbeiten Sie das benötigte `event_type` und geben Sie eine erfolgreiche `2xx`-Antwort erst zurück, nachdem das Ereignis verarbeitet wurde. Für lokale Tests können Sie den Handler auf Ihrem Computer starten und über eine öffentliche HTTPS-URL erreichbar machen. Verwenden Sie dafür [ngrok](https://ngrok.com) oder einen anderen Tunneling-Dienst und tragen Sie die generierte öffentliche URL in den Webhook-Einstellungen ein. Senden Sie nach der Einrichtung einen Test-Webhook aus der Oberfläche und prüfen Sie den Zustellstatus. Für die Beispiel-URL muss Ihr Server `POST` auf `/gamemonitoring-webhook` annehmen. Wenn der Test fehlschlägt, orientieren Sie sich an der Handler-Antwort: `401` bedeutet Signaturfehler, `403` oder eine HTML-Prüfseite weist meist auf WAF oder Bot-Schutz hin, und Timeout bedeutet, dass die URL aus dem Internet nicht erreichbar ist oder zu langsam antwortet. ## Anforderungen an den Handler {#handler-requirements} - Die URL muss aus dem Internet erreichbar sein. Lokale Adressen, private Netzwerke und URLs mit Login oder Passwort sind nicht geeignet. - HTTPS wird für Produktion empfohlen. HTTP wird unterstützt, schützt Daten bei der Übertragung aber schwächer. - Der Handler muss die Methode `POST` und einen JSON-Body ohne Weiterleitungen annehmen. - Geben Sie `2xx` erst zurück, nachdem Ihr System das Ereignis verarbeitet hat. In der Regel reicht `204 No Content`. - Wenn das Ereignis nicht sicher verarbeitet werden kann, geben Sie einen Fehlercode zurück. `3xx`, `4xx`, `5xx`, Timeout und Verbindungsfehler gelten als fehlgeschlagene Zustellung. - Wenn Sie Firewall, Bot-Schutz oder eine Allowlist verwenden, fügen Sie die [IP-Adressen von GAMEMONITORING](https://gamemonitoring.de/developers/docs/ips) als Ausnahmen hinzu. - Geben Sie im Antwort-Body keine Tokens, Stack Traces, SQL-Fehler oder andere interne Details zurück. Die Handler-Antwort wird in der Oberfläche angezeigt, daher muss der Fehlertext sicher und verständlich sein. ## Ereignisdaten {#event-data} Jeder Webhook kommt mit einem JSON-Body und Basisfeldern: - `event_type` — welches Ereignis verarbeitet werden muss. - `event_id` — eindeutige Ereignis-ID. Verwenden Sie sie zusammen mit `event_type` für Idempotenz und Schutz vor wiederholter Zustellung. - `is_test` — kennzeichnet eine Testzustellung aus der Oberfläche. - `signature` — Signatur des Ereignis-Bodys. **Webhook-Ereignisbeispiel** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "example.event", "is_test": false, "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064" } ``` So lesen Sie das Beispiel: `event_type` zeigt, welches Ereignis verarbeitet werden muss; `event_id` wird für Idempotenz vor Zustandsänderungen benötigt; `is_test: true` bedeutet eine technische Zustellprüfung; `signature` ist keine Geschäftsdaten und wird nur zur Authentifizierung der Anfrage verwendet. Die Verarbeitungslogik hängt von `event_type` ab. Für `server.vote` und `project.vote` nutzen Sie den eigenen Ablauf: [Belohnungen für Stimmen](https://gamemonitoring.de/developers/docs/webhook/vote#flow). Wenn `is_test` `true` ist, prüfen Sie die Signatur und geben `2xx` zurück, ändern aber keinen Kontostand, geben keine Gegenstände aus und starten keine produktiven Vorgänge. ## Antwortbeispiel des Handlers {#response-example} Schließen Sie jedes eingehende Ereignis mit einem klaren Ergebnis ab: - `204 No Content` — die Signatur ist korrekt, und das Ereignis wurde verarbeitet oder sicher übersprungen. Geben Sie dieselbe Antwort für eine Testzustellung und für ein bereits verarbeitetes Ereignis zurück. - `400 Bad Request` — Pflichtfelder fehlen. Das bedeutet einen Handler-Fehler oder einen unerwarteten Request-Body; Geschäftslogik darf nicht gestartet werden. - `401 Unauthorized` — die Signatur ist falsch. Führen Sie keine API-Anfragen aus, ändern Sie keine Datenbank und geben Sie keine Belohnungen aus. - `500 Internal Server Error` — Ihre Datenbank, Queue oder ein internes System ist vorübergehend nicht verfügbar. Die Zustellung bleibt fehlerhaft und kann nach Behebung der Ursache wiederholt werden. Beispiel: Wenn der Handler das Ereignis empfangen, die Signatur geprüft, `event_type` + `event_id` gespeichert und das Ereignis verarbeitet hat, kann er `204` zurückgeben. Ist die Datenbank nicht verfügbar und kann das Ereignis nicht gespeichert werden, geben Sie besser `500` zurück, damit die Zustellung nicht zu früh als erfolgreich markiert wird. ## Signaturprüfung {#signature} Die Signatur befindet sich im Feld `signature`. Prüfen Sie sie vor jeder Geschäftslogik, vor API-Anfragen und vor Datenbankänderungen. Nehmen Sie zur Prüfung alle Felder des Ereignis-Bodys außer `signature`, sortieren Sie die Schlüssel alphabetisch und bauen Sie eine Zeichenkette `key=value`, verbunden mit `&`. Boolesche Werte werden als `true` oder `false` geschrieben. **Signatur-String** ```text event_id=9824cabb-2203-437e-9b6c-aba43dde3e4b&event_type=example.event&is_test=false ``` Für das Beispiel oben wird der Signatur-String nur aus `event_id`, `event_type` und `is_test` gebaut. Danach berechnen Sie `HMAC-SHA256` mit dem Signatur-Token aus den Webhook-Einstellungen und vergleichen das Ergebnis mit `signature` aus der Anfrage. Vorberechnete Signaturen in den Beispielen nutzen den Demo-Token `paste-webhook-token-here`. In Ihrem Handler verwenden Sie den Token aus den Webhook-Einstellungen. Im Handler: - bauen Sie den Signatur-String aus sortierten Schlüsseln; - berechnen Sie `HMAC-SHA256` mit dem Signatur-Token; - vergleichen Sie das Ergebnis mit `signature` über eine Funktion mit konstanter Vergleichszeit: `hash_equals` in PHP, `timingSafeEqual` in Node.js oder `compare_digest` in Python; - geben Sie `401` zurück, wenn die Signatur falsch ist. ## Schritt 1. Basis-Handler {#minimal-handler} Beginnen Sie mit einem Handler, der jeden Webhook annehmen kann: Er liest JSON, prüft `signature`, verarbeitet die Testzustellung, prüft Basisfelder und gibt `204` zurück. In diesem Schritt bestätigt der Handler nur, dass die Zustellung korrekt angenommen wird. Ereignisspezifische Logik fügen Sie hinzu, nachdem dieser Basispfad funktioniert. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Add event-specific logic here. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); // 204 tells GAMEMONITORING that the delivery was accepted successfully. http_response_code(204); ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Add event-specific logic here. console.log('Accepted webhook event ' + eventType + ' #' + eventId) // 204 tells GAMEMONITORING that the delivery was accepted successfully. return res.sendStatus(204) }) app.listen(3000) ``` ### Python ```python import hashlib import hmac from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Add event-specific logic here. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) # 204 tells GAMEMONITORING that the delivery was accepted successfully. return '', 204 ``` ## Schritt 2. Deduplikation hinzufügen {#deduplication} Webhook nutzt At-least-once-Zustellung: dasselbe Ereignis kann mehrmals ankommen. Bevor der Handler den Zustand Ihres Systems ändert, machen Sie diese Operation anhand von `event_type` + `event_id` idempotent. Erstellen Sie zuerst eine Tabelle, die das Paar `event_type` und `event_id` mit eindeutigem Schlüssel speichert. Wenn der Datensatz bereits existiert, wurde das Ereignis schon verarbeitet. **Tabelle verarbeiteter Webhook-Ereignisse** ```sql CREATE TABLE gamemonitoring_webhooks ( event_type varchar(64) NOT NULL, event_id varchar(100) NOT NULL, created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (event_type, event_id) ); ``` Erweitern Sie danach den Basis-Handler: Speichern Sie nach Signaturprüfung und Prüfung der Basisfelder `event_type` + `event_id` und führen Sie Zustandsänderungen in derselben Transaktion aus. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Deduplicate it before event-specific logic. $pdo = null; try { // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Deduplicate it before event-specific logic. let connection try { connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Deduplicate it before event-specific logic. connection = None try: connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` Verwenden Sie Nickname, Benutzer-ID oder Server-ID nicht als Deduplikationsschlüssel: Ein Benutzer kann verschiedene Ereignisse auslösen oder eine erlaubte Aktion später wiederholen. Der Schlüssel muss `event_type` + `event_id` sein. Beispiel: Der Handler hat den Zustand Ihres Systems geändert, aber die Verbindung brach ab, bevor GAMEMONITORING `204` erhielt. Später wird die Zustellung wiederholt, und dasselbe Ereignis kommt erneut an. Ihr Handler muss die bereits gespeicherten `event_type` + `event_id` finden, die wiederholte Zustandsänderung überspringen und `204` zurückgeben. Wenn der Handler ein Ereignis vorübergehend nicht verarbeiten kann, geben Sie eine Fehlerantwort zurück. Nach Behebung der Ursache kann die Zustellung aus der Oberfläche wiederholt werden, sofern eine Wiederholung für dieses Ereignis verfügbar ist. ## Tests und erneute Zustellung {#tests-resend} Eine Testzustellung (`is_test: true`) prüft URL, Signatur und HTTP-Antwort des Handlers. Der Handler muss denselben Verarbeitungspfad durchlaufen: JSON lesen, `signature` prüfen, `is_test` erkennen und eine erfolgreiche `2xx`-Antwort zurückgeben. Ein Testereignis darf Kontostand, Inventar, Rollen, Abonnements oder andere produktive Daten nicht ändern. Für den Test reichen ein technischer Logeintrag und die Antwort `204`. Wenn die Zustellung fehlschlägt, zeigt die Oberfläche Status, HTTP-Code und Handler-Antwort. Nach Behebung der Ursache kann eine fehlgeschlagene Zustellung erneut gesendet werden, sofern eine Wiederholung für dieses Ereignis verfügbar ist. https://gamemonitoring.de/developers/docs/webhook.md --- # Belohnungen für Stimmen {#vote-rewards} Belohnungen für Stimmen nutzen die Webhook-Ereignisse `server.vote` und `project.vote`: Der Handler empfängt das Ereignis, ruft Stimmdaten über die API ab und gibt die Belohnung nur einmal aus. Richten Sie zuerst den [Projekt-Webhook](https://gamemonitoring.de/developers/docs/webhook#connect) und die Prüfung von [signature](https://gamemonitoring.de/developers/docs/webhook#signature) ein. Stimmdaten werden über [GET /votes/:vote_id](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__GET) abgefragt. ## So funktioniert der Ablauf {#flow} 1. Nehmen Sie das Webhook-Ereignis an und prüfen Sie [signature](https://gamemonitoring.de/developers/docs/webhook#signature). Wenn [is_test](https://gamemonitoring.de/developers/docs/webhook#tests-resend) `true` ist, geben Sie `204` zurück, ohne die Stimme abzurufen und ohne eine Belohnung auszugeben. 2. Stellen Sie sicher, dass `event_type` `server.vote` oder `project.vote` ist. 3. Verwenden Sie `event_id` als ID der Stimme. 4. Rufen Sie Stimmdaten über [GET /votes/:vote_id](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__GET) ab und finden Sie den Spieler in Ihrem System. 5. Wenden Sie in einer Transaktion den [Schutz vor erneuter Verarbeitung](https://gamemonitoring.de/developers/docs/webhook#deduplication) über `event_type` + `event_id` an und geben Sie die Belohnung nur für ein neues Ereignis aus. 6. Wenn die Belohnung nicht sicher ausgegeben werden kann, geben Sie eine Fehlerantwort zurück. Nach Behebung der Ursache [wiederholen Sie die Zustellung](https://gamemonitoring.de/developers/docs/webhook#tests-resend) aus der Oberfläche. ## Belohnungsbeispiel {#reward-example} Angenommen, Spieler `PlayerName` hat für den Server mit ID `1` gestimmt, und Ihr System soll ihm `100` Münzen gutschreiben. 1. GAMEMONITORING sendet einen Webhook mit `event_type: server.vote` und `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b`. 2. Der Handler prüft [signature](https://gamemonitoring.de/developers/docs/webhook#signature). Bei falscher Signatur gibt er `401` zurück und stoppt. 3. Der Handler ruft `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b` auf, erhält Nickname, Server und Benutzer und findet das lokale Konto. 4. In einer Transaktion speichert der Handler `event_type` + `event_id` für den [Schutz vor erneuter Verarbeitung](https://gamemonitoring.de/developers/docs/webhook#deduplication). 5. Für ein neues Ereignis schreibt der Handler `100` Münzen in derselben Transaktion gut. 6. Bei erneuter Zustellung findet der Handler das bereits gespeicherte Ereignis, gibt die Belohnung nicht erneut aus und gibt `204` zurück. Der gleiche Ablauf eignet sich auch für Gegenstände, Rollen, VIP-Zeit, Promo-Codes oder Aufgaben in einer internen Queue. ## Stimmenereignis {#vote-event} Für eine Serverstimme sendet GAMEMONITORING `server.vote`, für eine Projektstimme `project.vote`. Der Ereignis-Body enthält nur Zustelldaten: `event_type`, `event_id`, `is_test` und `signature`. Vollständige Stimmdaten müssen separat abgefragt werden. **Ereignisbeispiel** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "server.vote", "is_test": false, "signature": "ae83b8aba88a3a9ab3b97b1f6d65664da5628a9cb64d56d5132807bca5472e4f" } ``` In diesem Ereignis ist `event_id` die ID der Stimme. Verwenden Sie den Webhook-Body nicht als Quelle für Nickname, Server oder Benutzer: Diese Daten kommen aus der API. ## Stimmdaten abrufen {#fetch-vote} Verwenden Sie `event_id` als `vote_id` und rufen Sie die Stimmdaten über [GET /votes/:vote_id](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__GET) ab: **Anfrage der Stimmdaten** ```bash curl -sS "https://api.gamemonitoring.de/votes/9824cabb-2203-437e-9b6c-aba43dde3e4b" ``` Für die Belohnung benötigen Sie normalerweise `response.nickname`, `response.server` und öffentliche Daten aus `response.user`. Wenn die Belohnung von einem bestimmten Server abhängt, prüfen Sie immer `response.server.id`. So verwenden Sie die Felder: `response.nickname` hilft, das Spielerkonto in Ihrer Datenbank zu finden, `response.server.id` wählt die Belohnungsregel für den Server aus, und `response.user.id` kann im Belohnungsprotokoll als GAMEMONITORING-Benutzer-ID gespeichert werden. Wenn die API vorübergehend nicht verfügbar ist oder eine unerwartete Antwort liefert, geben Sie keine Belohnung ohne Prüfung aus. Geben Sie einen Fehlercode zurück, beheben Sie die Ursache und [wiederholen Sie die Zustellung](https://gamemonitoring.de/developers/docs/webhook#tests-resend) aus der Oberfläche. ## Schritt 3. Handler für Stimm-Belohnungen {#complete-example} Das Beispiel setzt den Basis-Handler fort: Es prüft die Signatur, ruft Stimmdaten ab, schützt das Ereignis vor erneuter Verarbeitung und schreibt die Belohnung in einer Transaktion gut. Ersetzen Sie den Namen der Benutzertabelle, das Kontostandfeld und die Regel zur Spielersuche durch die Struktur Ihres Systems. Vor dem Start des Beispiels richten Sie den [Projekt-Webhook](https://gamemonitoring.de/developers/docs/webhook#connect) ein, prüfen [GET /votes/:vote_id](https://gamemonitoring.de/developers/docs/api/votes/:vote_id/__GET) und ersetzen die SQL-Updates für Benutzer durch Ihr Kontomodell. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // This reward handler processes server and project vote events. if (!in_array($eventType, ['server.vote', 'project.vote'], true)) { http_response_code(204); exit; } // At this point the webhook is trusted. Load vote data before opening a database transaction. $pdo = null; try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. $voteUrl = $apiUrl . '/votes/' . rawurlencode($eventId); $voteContext = stream_context_create(['http' => ['timeout' => 5]]); $voteBody = @file_get_contents($voteUrl, false, $voteContext); if ($voteBody === false) { throw new RuntimeException('Vote API request failed'); } $voteResponse = json_decode($voteBody, true) ?: []; $vote = $voteResponse['response'] ?? null; // Do not issue a reward when the vote response is missing a concrete nickname. if (!is_array($vote) || !isset($vote['nickname']) || !is_string($vote['nickname'])) { throw new RuntimeException('Vote API response does not include nickname'); } // Verify that the API entity matches the event before changing the account. $expectedEntityType = $eventType === 'project.vote' ? 'project' : 'server'; if (($vote['entity_type'] ?? '') !== $expectedEntityType) { throw new RuntimeException('Vote entity type does not match event type'); } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. $nickname = trim($vote['nickname']); if ($nickname === '') { throw new RuntimeException('Vote nickname is empty'); } // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. $balance = $pdo->prepare('UPDATE users SET balance = balance + ? WHERE nickname = ?'); $balance->execute([$rewardAmount, $nickname]); // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add the GAMEMONITORING API URL and reward settings for vote events. const apiUrl = 'https://api.gamemonitoring.de' const rewardAmount = '1.00' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // This reward handler processes server and project vote events. if (!['server.vote', 'project.vote'].includes(eventType)) { return res.sendStatus(204) } // At this point the webhook is trusted. Load vote data before opening a database transaction. let connection try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. const voteUrl = apiUrl + '/votes/' + encodeURIComponent(eventId) const voteResponse = await fetch(voteUrl, { signal: AbortSignal.timeout(5000) }) if (!voteResponse.ok) { throw new Error('Vote API request failed') } const voteBody = await voteResponse.json() const vote = voteBody.response // Do not issue a reward when the vote response is missing a concrete nickname. if (!vote || typeof vote.nickname !== 'string') { throw new Error('Vote API response does not include nickname') } // Verify that the API entity matches the event before changing the account. const expectedEntityType = eventType === 'project.vote' ? 'project' : 'server' if (vote.entity_type !== expectedEntityType) { throw new Error('Vote entity type does not match event type') } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. const nickname = vote.nickname.trim() if (!nickname) { throw new Error('Vote nickname is empty') } connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. await connection.execute('UPDATE users SET balance = balance + ? WHERE nickname = ?', [rewardAmount, nickname]) // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql import requests from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add the GAMEMONITORING API URL and reward settings for vote events. api_url = 'https://api.gamemonitoring.de' reward_amount = '1.00' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # This reward handler processes server and project vote events. if event_type not in ('server.vote', 'project.vote'): return '', 204 # At this point the webhook is trusted. Load vote data before opening a database transaction. connection = None try: # Load full vote data by event_id. Nickname, entity, and user data # are not in the webhook body. Return 500 if the API cannot confirm the vote. vote_url = f"{api_url}/votes/{event_id}" response = requests.get(vote_url, timeout=5) if not response.ok: raise RuntimeError('Vote API request failed') vote = response.json().get('response') # Do not issue a reward when the vote response is missing a concrete nickname. if not isinstance(vote, dict) or not isinstance(vote.get('nickname'), str): raise RuntimeError('Vote API response does not include nickname') # Verify that the API entity matches the event before changing the account. expected_entity_type = 'project' if event_type == 'project.vote' else 'server' if vote.get('entity_type') != expected_entity_type: raise RuntimeError('Vote entity type does not match event type') # Use vote nickname to update the local account. The entity id is available in # vote.entity_id and in either vote.server.id or vote.project.id. nickname = vote['nickname'].strip() if not nickname: raise RuntimeError('Vote nickname is empty') connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. cursor.execute('UPDATE users SET balance = balance + %s WHERE nickname = %s', (reward_amount, nickname)) # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` https://gamemonitoring.de/developers/docs/webhook/vote.md --- # System-IP-Adressen Diese IP-Adressen nutzt GAMEMONITORING, um Spielserver zu prüfen und [Webhook-Requests](https://gamemonitoring.de/developers/docs/webhook#connect) an Ihr System zuzustellen. Fügen Sie sie zur Allowlist hinzu, wenn Server, Website, WAF, CDN oder Bot-Protection eingehende Requests einschränken. ## Wann Sie sie hinzufügen sollten {#when-needed} - der Spielserver akzeptiert Requests nur von erlaubten Adressen; - der [Webhook-Handler](https://gamemonitoring.de/developers/docs/webhook#handler-requirements) ist durch Firewall, WAF oder Cloudflare geschützt; - Bot-Protection blockiert automatische Requests; - der Hosting-Anbieter verlangt IP-Adressen für Netzwerkregeln. ## Anwendungsbeispiel {#usage-example} Webhook-Beispiel: Ihr Handler liegt unter `https://panel.example.com/gamemonitoring-webhook` und die Domain ist durch Cloudflare geschützt. Fügen Sie GAMEMONITORING-IP-Adressen für diese Domain oder den genauen Pfad zur Allowlist hinzu, damit Cloudflare keine Challenge zeigt und [Webhook-`POST`-Requests](https://gamemonitoring.de/developers/docs/webhook#handler-requirements) nicht blockiert. Spielserver-Beispiel: Die Firewall erlaubt den Query-Port nur vertrauenswürdigen Adressen. Fügen Sie GAMEMONITORING-IP-Adressen zur Regel für den Query-Port hinzu, sonst kann das Monitoring Online-Status und Serverzustand nicht zuverlässig prüfen. ## Allowlist konfigurieren {#allowlist} Geben Sie die IP-Adressen aus der Liste oben an Ihren Systemadministrator oder Hosting-Anbieter weiter. Die Regel muss eingehende Requests von diesen Adressen zu Ihrem Spielserver oder Webhook-Handler erlauben. Wenn die Regel pfadbasiert ist, beschränken Sie sie auf den benötigten Endpoint, zum Beispiel `/gamemonitoring-webhook`. Wenn sie portbasiert ist, geben Sie nur den Query-Port des Spiels oder den Webserver-Port für Webhook an. ## Nach der Konfiguration prüfen {#verification} Senden Sie nach der Änderung einen Testrequest oder [Test-Webhook](https://gamemonitoring.de/developers/docs/webhook#tests-resend) und prüfen Sie, dass der Request nicht mehr blockiert wird. Wenn die Prüfung fehlschlägt, prüfen Sie Firewall-, WAF- oder Cloudflare-Logs. Dort sollten Quell-IP, Pfad und Blockierungsgrund sichtbar sein. So finden Sie fehlende Domain, Pfad, Port oder Regelreihenfolge. ## Cloudflare-Konfiguration {#cloudflare} Wenn der Webhook-Handler hinter Cloudflare liegt, fügen Sie GAMEMONITORING-IP-Adressen zu einer Regel hinzu, die WAF-Prüfungen für diese Requests überspringt: 1. Melden Sie sich im Cloudflare-Dashboard an. 2. Wählen Sie die Domain. 3. Öffnen Sie **Security**. 4. Wählen Sie **WAF**. 5. Öffnen Sie **Custom rules**. 6. Klicken Sie **Create rule**. 7. Setzen Sie einen klaren Namen, zum Beispiel **Allow GAMEMONITORING**. 8. Wählen Sie in **Field** den Wert **IP Source Address**. 9. Wählen Sie in **Operator** den Wert **is in**. 10. Fügen Sie in **Value** die IP-Adressen aus der Liste oben hinzu. 11. Wählen Sie in **Choose action** den Wert **Skip**. 12. Wählen Sie in **WAF components to skip** die Prüfungen, die Requests zu Ihrem Handler blockieren. 13. Wählen Sie in **Select order** den Wert **First**. 14. Klicken Sie **Deploy**. Wenn Requests danach weiterhin blockiert werden, prüfen Sie Firewall- oder Cloudflare-Logs und stellen Sie sicher, dass die Regel auf die richtige Domain und den Handler-Pfad angewendet wird. ```http GET https://api.gamemonitoring.de/pages/system/ips ``` https://gamemonitoring.de/developers/docs/ips.md