Einen Discord-Webhook erstellen, um Nachrichten automatisch zu posten

Was ist ein Discord-Webhook?

Ein Discord-Webhook ist eine kanalspezifische URL, mit der ein externer Dienst eine Nachricht in diesen Kanal postet, indem er eine HTTP-Anfrage sendet, ganz ohne sich als Bot oder Nutzer anzumelden. Discords eigene Entwicklerdokumentation beschreibt den Endpunkt als POST /webhooks/{webhook.id}/{webhook.token} und stellt unmissverständlich fest, dass "this call does not require authentication" (dieser Aufruf erfordert keine Authentifizierung), weil die in der URL eingebetteten Werte id und token selbst die Zugangsdaten sind. Diese eine Tatsache bestimmt das meiste, was ein Team über die Einrichtung wissen muss: Das Erstellen des Webhooks ist ein einmaliger, berechtigungspflichtiger Schritt innerhalb von Discord, während die spätere Nutzung so einfach ist wie das Senden von JSON an eine URL.

Wie erstellst du einen Discord-Webhook in den Kanaleinstellungen?

Ein Servermitglied mit der Berechtigung Manage Webhooks erstellt einen Discord-Webhook direkt aus den Einstellungen eines Kanals, im Tab Integrationen, indem es New Webhook wählt und die von Discord dafür generierte URL kopiert. Dieselbe Aktion steht über Discords API als POST /channels/{channel.id}/webhooks zur Verfügung, wofür laut Discords Dokumentation ebenfalls die Berechtigung Manage Webhooks auf diesem Kanal nötig ist. Benenne den Webhook und gib ihm bei Bedarf einen Avatar, bevor du die URL kopierst, denn ab diesem Zeitpunkt kann jeder mit dieser URL in den Kanal posten.

Wie sieht ein JSON-Payload für einen Discord-Webhook aus?

Ein JSON-Payload für einen Discord-Webhook ist der Request-Body, der an die Webhook-URL gesendet wird, und er muss mindestens eines von content, embeds, poll oder einem Dateianhang enthalten, da Discords eigene Dokumentation das als Voraussetzung für den Aufruf zum Ausführen des Webhooks nennt. Das Feld content trägt reinen Nachrichtentext mit bis zu 2000 Zeichen, während username und avatar_url den Standardnamen und das Standardbild des Webhooks nur für diese eine Nachricht überschreiben, und embeds transportiert bis zu 10 reichhaltig formatierte Embed-Objekte in einem einzigen Aufruf. Der Mechanismus ist ein gewöhnlicher JSON-POST-Body: Ein Dienst baut dieses Objekt, sendet es per HTTPS an die Webhook-URL, und Discord postet das Ergebnis in den Kanal, in dem der Webhook erstellt wurde.

{
  "content": "Deployment finished",
  "username": "Release Bot",
  "avatar_url": "https://example.com/bot-avatar.png",
  "embeds": []
}

Welche Rate Limits gelten für einen Discord-Webhook?

Laut Discords eigener Entwicklerdokumentation setzt Discord ein globales Limit von 50 Anfragen pro Sekunde und Anwendung über die gesamte API hinweg durch, und die eigene Route eines Webhooks trägt ein separates, engeres Limit, das Discord über Antwort-Header statt über eine einzige veröffentlichte Zahl mitteilt. Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, und Discords Dokumentation weist einen Client an, diese Header auszulesen statt ein Limit fest einzuprogrammieren, da Limits pro Route "subject to change" (jederzeit änderbar) sind. Ein Dienst, der viele Nachrichten in einem Schub sendet, muss nach jedem Aufruf den Remaining-Requests-Header prüfen und pausieren, sobald dieser null erreicht, statt eine feste Zahl von Aufrufen pro Minute anzunehmen.

Warum ist eine Discord-Webhook-URL ein Geheimnis?

Eine Discord-Webhook-URL ist ein Geheimnis, weil die darin enthaltenen Werte id und token die gesamten Zugangsdaten sind, die der Endpunkt prüft, und Discords eigene Dokumentation bestätigt, dass der Aufruf zum Ausführen des Webhooks keine zusätzliche Authentifizierung braucht über das hinaus, was die URL bereits trägt. Wer diese URL besitzt, kann jede beliebige Nachricht unter dem Namen des Webhooks in diesen Kanal posten, ohne sich jemals als Discord-Nutzer oder Bot zu authentifizieren. Speichere die URL so, wie ein API-Key gespeichert wird, etwa in einer Umgebungsvariable oder einem Secrets-Manager, und committe sie niemals in ein öffentliches Code-Repository oder füge sie in ein clientseitiges Skript ein.

Kann ein Discord-Webhook auch Nachrichten empfangen, nicht nur senden?

Ein Standard-Discord-Webhook sendet nur Nachrichten in einen Kanal; er kann keine Nachrichten lesen, die andere dort posten, da der Endpunkt zum Ausführen des Webhooks nur in eine Richtung als POST-Ziel dient, ohne entsprechenden Lesezugriff. Ein Team, das darauf reagieren will, was innerhalb eines Discord-Servers passiert, so wie Reddit-API-Rate-Limits eine zweiseitige Integration mit Reddit regeln, braucht stattdessen einen Discord-Bot mit eigenem Token und den passenden Gateway-Berechtigungen. Das ist ein anderer Aufbau als ein Webhook, näher an dem, wie Twitter-API-Preise den zweiseitigen Zugriff auf die eigenen Daten von X reguliert, und gehört eher zur Seite Social-Media-Datenerfassung eines Projekts als zur Alerting-Seite; Discords eigene Entwicklerdokumentation im Stil eines Einstiegsleitfadens ist die richtige nächste Anlaufstelle für ein Team, das einen vollständigen Bot baut.

Häufig gestellte Fragen

Kann ich eine Nachricht, die ich bereits mit einem Discord-Webhook gesendet habe, bearbeiten oder löschen?

Ja. Die Antwort auf den Aufruf zum Ausführen des Webhooks von Discord gibt eine message id zurück, wenn die Anfrage ?wait=true enthält, und diese id lässt sich mit separaten Edit- und Delete-Endpunkten desselben Webhooks verwenden. Ohne wait=true liefert der erste Aufruf nicht das Message-Objekt, das für eine spätere Bearbeitung nötig ist.

Läuft ein Discord-Webhook irgendwann ab?

Eine Discord-Webhook-URL läuft nicht von selbst ab; sie bleibt gültig, bis ein Server-Admin den Webhook löscht oder den Kanal entfernt, zu dem er gehört. Da sie nie von selbst abläuft, ist es die sicherere Annahme, die URL als dauerhaftes Geheimnis zu behandeln, nicht als temporäres Token.

Können mehrere Dienste dieselbe Discord-Webhook-URL verwenden?

Ja, technisch können beliebig viele Dienste Anfragen an dieselbe Webhook-URL senden, da Discord nicht unterscheidet, welcher Absender den Aufruf gemacht hat. In der Praxis lassen sich Nachrichten leichter zu ihrer Quelle zurückverfolgen, wenn pro Dienst oder pro Bot ein eigener Webhook verwendet wird, und eine Integration lässt sich widerrufen, ohne eine andere zu unterbrechen.

Was passiert, wenn ich ein Payload sende, das größer ist als die Grenzwerte von Discord?

Discord lehnt die Anfrage mit einer Fehlerantwort ab, statt den Inhalt stillschweigend zu kürzen, sodass ein Payload mit mehr als 2000 Zeichen in content oder mehr als 10 Objekten in embeds den Aufruf komplett scheitern lässt. Wer nach jedem Webhook-Aufruf den Statuscode der Antwort prüft, bemerkt das, bevor eine Nachricht stillschweigend nie ankommt.

Muss zwingend der Server-Besitzer einen Discord-Webhook erstellen?

Nein. Jedes Mitglied mit der Berechtigung Manage Webhooks auf einem Kanal kann dort einen Webhook erstellen, und diese Berechtigung lässt sich einer Rolle zuweisen, ohne diese Rolle zum Server-Besitzer oder Administrator zu machen. Discords API erzwingt dieselbe Berechtigungsprüfung auch am Endpunkt POST /channels/{channel.id}/webhooks, der zum programmatischen Erstellen dient.

Ist ein Discord-Webhook dasselbe wie ein Discord-Bot?

Nein. Ein Webhook ist eine Einweg-URL zum Posten von Nachrichten in einen einzelnen Kanal, ganz ohne Login, während ein Bot eine vollständige Anwendung mit eigenem Token ist, die Nachrichten lesen, auf Befehle reagieren und über viele Kanäle und Server hinweg agieren kann. Ein Projekt, das nur Benachrichtigungen in einen Kanal pushen muss, braucht einen Webhook; ein Projekt, das zuhören und reagieren muss, braucht einen Bot.

Kann ich einen Discord-Webhook einrichten, ohne Code zu schreiben?

Das Erstellen erfordert keinen Code: Ein Server-Mitglied mit der Berechtigung Manage Webhooks öffnet den Integrations-Tab des Kanals, klickt auf New Webhook und kopiert die generierte URL. Einen Namen oder ein Avatar für den Webhook festzulegen ist an dieser Stelle optional. Um tatsächlich eine Nachricht zu senden, braucht es trotzdem einen Weg, eine HTTPS-POST-Anfrage mit einem JSON-Body zu schicken, sei es ein Skript, ein Automatisierungstool oder ein Dienst, der bereits JSON spricht.

Woran erkenne ich, wie viele Anfragen mir bleiben, bevor ich Discords Rate Limit erreiche?

Discord veröffentlicht keine feste Zahl für die eigene Route eines Webhooks; stattdessen enthält jede Antwort die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Discords eigene Dokumentation verlangt, dass ein Client diese Header ausliest, statt ein Limit fest einzuprogrammieren, da sich Limits pro Route ändern können. Ein Dienst, der viele Nachrichten in kurzer Folge sendet, prüft nach jedem Aufruf den Remaining-Header und pausiert, sobald er auf null steht.

Kann eine Webhook-Nachricht so aussehen, als käme sie von jemand anderem?

Die Felder username und avatar_url im JSON-Payload überschreiben Name und Bild des Webhooks, aber nur für diese eine Nachricht. Der eigentlich konfigurierte Name und das Avatar des Webhooks bleiben überall sonst unverändert. So kann ein Webhook für eine Deployment-Meldung als "Release Bot" posten und beim nächsten Mal unter einem anderen Namen, ohne den Webhook selbst zu bearbeiten.

Was hindert jemand anderen daran, in meinen Kanal zu posten, wenn er meine Webhook-URL bekommt?

Nichts. Die Webhook-ID und das Token in der URL sind das gesamte Credential, das Discord prüft, also kann jeder mit dieser URL jede beliebige Nachricht unter dem Namen des Webhooks posten, ohne sich als Nutzer oder Bot anzumelden. Deshalb sollte die URL wie ein API-Key behandelt werden: in einer Umgebungsvariable oder einem Secrets-Manager gespeichert, niemals in ein öffentliches Repository committet oder in clientseitigen Code eingefügt.