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 Execute.

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 (Execute + 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.

Execute-Anfrage

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 aufgelöste 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 an Ort und Stelle. Lösche den Webhook und erstelle einen neuen. Der alte Token funktioniert sofort nach dem Löschen nicht mehr (der Execute-Pfad schließt soft-gelöschte Zeilen aus).

Unterschiede zu Discord

Webhooks gehören der Anwendung, nicht einer Server-Administration. Das Löschen des Kanals löscht den Webhook-Datensatz nicht; das nächste Execute gibt beim Kanal-Join in der Abfrage 404 zurück.
Kein Überschreiben von username / avatar_url pro Anfrage. Die Identität ist fest auf den Bot-Benutzer gesetzt.
Es gibt keine Obergrenze pro Kanal; die Grenze gilt pro Anwendung (50).
Die Authentifizierung wird mit bcrypt geprüft, der Token-Vergleich ist also bewusst langsam. Hämmere den Endpunkt nicht in engen Schleifen.
Selbst gehostete Server: Webhooks werden nicht an selbst gehostete Instanzen weitergeleitet. Alle Webhook-Endpunkte geben für selbst gehostete Guild-Ziele 404 zurück. Siehe Doku zu selbst gehosteten Servern.

← Zurück zur Doku