App-Webhooks

Ein App-Webhook ist eine kanalbezogene URL, an die dein CI-Runner, dein Monitoring oder ein externer Dienst POSTen kann, um eine Nachricht in einen GameVox-Kanal zu legen. Keine Gateway-Sitzung nötig. Nachrichten erscheinen als dein Bot-Benutzer, mit Avatar und Benutzernamen des Bots.

Grenzwerte

50 Webhooks pro Anwendung.
Name: 1–80 Zeichen.
Inhalt: 1–4000 Zeichen pro Nachricht.
Ein Webhook = ein Kanal. Zum Erstellen eines Webhooks brauchst du die Berechtigung manage_server im Server des Kanals.

Token-Format

WH.{8-Zeichen-Präfix}.{Base64-Zufallswert}

Beispiel: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Der vollständige Token wird genau einmal beim Erstellen angezeigt. Wir speichern nur den bcrypt-Hash sowie das Präfix und die letzten 4 Zeichen zur Anzeige. Verlierst du einen Token, lösche den Webhook und erstelle einen neuen.

Einen Webhook erstellen (Portal)

Öffne deine Anwendung → Tab Webhooks → Neuer Webhook. Wähle einen Server, den du verwalten kannst, dann einen Kanal, und gib einen Namen an. Der Anzeigedialog zeigt den vollständigen Token und die einsatzbereite Execute-URL. Kopiere sie, bevor du ihn schließt; das Portal zeigt sie nie wieder.

Endpunkte

Zwei Authentifizierungsarten: Bot-Token für die Verwaltung, URL-Token für das Ausführen.

Authentifizierung per Bot-Token (Verwaltung)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Authentifizierung per URL-Token (Ausführen + Bearbeiten)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

Für URL-Token-Routen gibt es keinen Authorization-Header. Der Token im URL-Pfad ist die Authentifizierung. Behandle die URL wie ein Geheimnis.

Ausführungsanfrage

JSON-Body:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "Build #4811 hat in der Produktion bestanden.",
  "embeds": [
    {
      "title": "CI grün",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 Tests, 0 Fehlschläge.",
      "color": 3066993
    }
  ]
}

multipart/form-data-Body (für Anhänge):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Siehe Screenshot", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Antwort (bei beiden Content-Types):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "Build #4811 hat in der Produktion bestanden.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Was unterstützt wird

Inhalt: reiner Text, 1–4000 Zeichen.
Embeds: vollständige Discord-Embed-Form (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Mehrere Embeds pro Nachricht sind erlaubt.
Anhänge: Dateien per multipart/form-data mit einem payload_json-Teil hochladen; die Antwort enthält CDN-URLs.
Antwortziel: übergib message_reference in payload_json.
?wait=true: implizit; die Antwort ist immer die resultierende Nachricht.
Bearbeiten / Löschen: PATCH / DELETE auf /webhooks/{id}/{token}/messages/{message.id} entsprechen Discord.
Überschreiben von Benutzername / Avatar: wird nicht unterstützt. Nachrichten erscheinen immer als der Bot-Benutzer der Anwendung.

Fehler

401: Token fehlt, ist fehlerhaft oder passt nicht.
404: Webhook gelöscht oder ID existiert nicht.
400: leerer content ohne Embeds/Anhänge, oder content länger als 4000 Zeichen.
405: Verb auf dieser Route nicht unterstützt.
413: Anhang überschreitet die Größenbeschränkung pro Datei.

Rotieren

In v1 gibt es keinen Endpunkt zum Rotieren ohne Neuerstellung. Lösche den Webhook und erstelle einen neuen. Der alte Token funktioniert sofort nach dem Löschen nicht mehr (der Ausführungspfad schließt soft-gelöschte Datensätze aus).

Unterschiede zu Discord

Webhooks gehören der Anwendung, nicht einem Server-Admin. Das Löschen eines Cloud-Kanals löscht auch seine Webhooks. Auf einem selbst gehosteten Server überdauert der Webhook-Datensatz einen gelöschten Kanal, und das Ausführen schlägt fehl, weil die Instanz den Kanal nicht mehr hat.
Kein Überschreiben von username / avatar_url pro Anfrage. Die Identität ist fest auf den Bot-Benutzer gesetzt.
Die Webhook-Obergrenze pro Kanal wird nicht erzwungen; die Grenze gilt pro Anwendung (50).
Die Authentifizierung wird mit bcrypt geprüft, der Token-Vergleich ist also bewusst langsam. Ruf den Endpunkt nicht massenhaft in engen Schleifen auf.
Selbst gehostete Server: Webhooks funktionieren wie in der Cloud. Die Webhook-Datensätze liegen in der Cloud, die Berechtigung zu ihrer Verwaltung wird von der Kundeninstanz geprüft, und ausgeführte Nachrichten werden in den selbst gehosteten Kanal geschrieben. Siehe Doku zu selbst gehosteten Servern.

← Zurück zur Doku