Wann ein Webhook sinnvoll ist
Nutze einen Webhook für Build-Benachrichtigungen, Ereignisse aus externen Diensten oder Updates. Er postet in einen vorab gewählten Textkanal. Um Nachrichten zu lesen, Befehle und Buttons zu verarbeiten oder auf Ereignisse zu reagieren, brauchst du einen Bot.
Einen Webhook anlegen
Öffne die Einstellungen eines Textkanals → Webhooks · automatisierte Nachrichten. Anlegen und Löschen von Webhooks erfordert MANAGE_CHANNELS. Speichere den zurückgegebenen Pfad und das Token: Das Geheimnis wird einmal angezeigt, gespeichert wird nur sein Hash.
| Konto-Token | Operation |
|---|---|
| GET /api/channels/:channelId/webhooks | Webhooks auflisten. |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}. |
| DELETE /api/channels/:channelId/webhooks/:id | Webhook löschen. |
Adresse und Kennung gehören zur API des Kanal-Hosts. Webhooks unterstützen keine Direktnachrichten, Gruppen und öffentlichen Räume.
Senden
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "Build fertig",
"description": "Die Version ist bereit zur Prüfung.",
"color": 5793266,
"fields": [{ "name": "Status", "value": "Bereit", "inline": true }]
}] }{"content":"Text"} wird ebenfalls unterstützt, bis 2000 Zeichen. Bis zu 10 Einbettungen mit insgesamt 6000 Zeichen. Begleitet Text die Einbettungen, belegt er einen Einbettungsplatz. Eine erfolgreiche 201-Antwort enthält message id und channel_id. Der Kanal wird in der Konfiguration festgelegt, nicht im Anfrage-Body.
Grenzen und Sicherheit
- Eine akzeptierte Anfrage pro Webhook alle 2 Sekunden. Bei 429 nutze Retry-After: 2.
- Autor und Avatar werden beim Anlegen des Webhooks festgelegt, nicht von einem beliebigen Absender. Nachrichten werden als Webhook gekennzeichnet.
- Beim Senden werden die Rechte des Erstellers geprüft. Verlorene Rechte können 403 ergeben.
- Wiederhole keine Anfrage mit unbekanntem Ergebnis, ohne zu prüfen: Idempotenz ist nicht implementiert.
- Sende das Geheimnis im Authorization-Header, nicht in der URL. Lösche und erstelle einen Webhook neu, wenn sein Geheimnis durchsickert.
- Vermeide personenbezogene Daten in Benachrichtigungen und externe Bild-URLs.