Discord-URL-Shortener-Benachrichtigungen: Telegram-Einrichtung, Payloads, Fallstricke

Wenn ein Kurzlink um 3 Uhr morgens mit 404 antwortet, soll die Benachrichtigung in demselben Chat landen, in dem dein On-Call-Team bereits aktiv ist. Für die meisten Entwicklungsteams ist das Discord; für Ops- und Growth-Teams in Europa häufig Telegram. Elido liefert Beta-Integrationen für beide. Dieser Artikel erklärt, was du eingibst, was am anderen Ende als JSON ankommt und welche drei Fehlerfälle Teams in der ersten Woche erwischen.

Zwei Fakten vorab. Erstens: Beide Konnektoren funktionieren ausschließlich per Token-Paste. Du erzeugst eine Webhook-URL oder ein Bot-Token in der Anbieteroberflache, trägst es in Elido ein, und die Integration ist aktiv. Wir richten auf der Discord- oder Telegram-Seite nichts automatisch ein, weil deren APIs das nicht ermöglichen. Zweitens: Jede Benachrichtigung wird vom gleichen Event-Bus ausgelöst, der auch das Webhooks-Feature antreibt - die Payload-Verträge sind daher stabil und dokumentiert.

Warum diese beiden Beta und nicht Live sind

Elido's Integrationskatalog markiert Integrationen als Live, wenn wir mit einem Klick drei Dinge erledigen können: die Anbieter-Ressource registrieren, die richtigen Scopes zuweisen und alles beim Trennen rückgängig machen. Notion, Linear und Pipedrive qualifizieren sich, weil sie OAuth plus eine Ressource-API bereitstellen.

Discord-Webhooks und Telegram-Bots tun das nicht. Die Discord-Webhooks-API benötigt einen Bot-Nutzer mit der Berechtigung "Webhooks verwalten" für einen bestimmten Kanal - einen Consent-Flow, den wir nicht selbst steuern können. Bei Telegram ist es noch schwieriger: BotFather ist eine chatbasierte Oberfläche ohne maschinenlesbare Token-Ausstellung. Daher bitten wir dich, 90 Sekunden Einrichtung auf Anbieterseite zu erledigen, und wir übernehmen alles danach. Das Token liegt in unserem Envelope-verschlüsselten Speicher und verlässt nie den api-core-Webhook-Dispatcher.

Das Beta-Abzeichen bedeutet: "Das funktioniert, die Payloads sind stabil, aber die Verbindungs-/Trennungs-UX erfordert einen zusätzlichen Schritt." Wenn du heute Auto-Provisioning benötigst, ist Slack als Live-Integration verfügbar und läuft auf demselben Transformer-Pipeline.

Einrichtung Schritt für Schritt: zuerst Discord

Öffne in Discord den Zielkanal, klicke auf das Zahnrad-Symbol und wähle Integrationen -> Webhooks -> Neuer Webhook. Gib ihm einen Namen wie elido-alerts, lade optional den Elido-Avatar aus /blog/covers hoch und kopiere die Webhook-URL. Sie sieht so aus:

https://discord.com/api/webhooks/123456789012345678/AbCdEf-tokenstring

Diese URL ist das Geheimnis. Jeder, der sie kennt, kann in deinen Kanal posten. Behandle sie wie ein Passwort.

Gehe in Elido zu Workspace-Einstellungen -> Integrationen -> Discord. Füge die URL ein, wähle die Ereignistypen aus der Mehrfachauswahl (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) und speichere. Das Formular sendet zuerst ein synthetisches Testereignis; gibt Discord etwas anderes als 204 zurück, schlägt das Speichern fehl und der Fehler wird direkt angezeigt.

Telegram erfordert zwei Schritte. Öffne einen Chat mit BotFather, führe /newbot aus, gib dem Bot einen Namen und kopiere das Token. Es sieht aus wie 7891234567:AAH-tokenstring. Füge dann den Bot dem Chat hinzu, in dem du Benachrichtigungen erhalten möchtest (Privatchat, Gruppe oder Kanal) und sende eine beliebige Nachricht. Füge in Elido das Token ein, klicke auf "Chats suchen", wähle aus der Liste der für den Bot sichtbaren Chats aus und speichere.

Der Schritt "Chats suchen" ruft einmalig Telegrams getUpdates auf, um Chat-IDs aufzulisten, die der Bot gesehen hat. Ist die Liste leer, wurde der Bot zwar hinzugefügt, hat aber noch keine Nachricht erhalten - sende eine und versuche es erneut.

Die tatsächliche Payload-Struktur

Hier werden die meisten "Alerts im Chat"-Tutorials vage. Das kommt tatsächlich an.

Für Discord senden wir ein einzelnes Embed pro Ereignis, nicht den veralteten content-String. Der Transformer unter services/api-core/internal/webhooks/delivery/transformers.go erzeugt diese Struktur:

{
  "username": "Elido",
  "embeds": [
    {
      "title": "Broken link detected",
      "description": "https://elido.me/launch -> 404 Not Found",
      "color": 15548997,
      "timestamp": "2026-06-04T09:14:22.000Z",
      "fields": [
        { "name": "Slug", "value": "launch", "inline": true },
        { "name": "Workspace", "value": "acme-prod", "inline": true },
        { "name": "Status", "value": "404", "inline": true },
        { "name": "First seen", "value": "2026-06-04 09:13:11 UTC" },
        { "name": "Last 5 redirects", "value": "blocked since 09:13:11" }
      ],
      "footer": { "text": "Elido alerts - broken_link" },
      "url": "https://elido.app/links/launch"
    }
  ]
}

Der color-Integer ist der Dezimalwert des Hex-Codes. Wir verwenden vier Schweregrade: info 3447003 (Blau), success 2280516 (Grün), warn 15844367 (Bernstein), error 15548997 (Rot). Mehr zu dieser Zuordnung gleich.

Telegram funktioniert anders. Wir verwenden parse_mode: "HTML", weil Markdown V2 ein Dutzend Zeichen escapen muss und schnell unübersichtlich wird. Der sendMessage-Aufruf sieht so aus:

{
  "chat_id": -1001234567890,
  "parse_mode": "HTML",
  "disable_web_page_preview": true,
  "text": "<b>Broken link detected</b>\n<code>elido.me/launch</code> -> 404\n\nSlug: <code>launch</code>\nWorkspace: <code>acme-prod</code>\nFirst seen: 2026-06-04 09:13:11 UTC\n\n<a href=\"https://elido.app/links/launch\">Open in Elido</a>"
}

Wir setzen disable_web_page_preview auf true, damit der Chat nicht aufgebläht wird, wenn die Alert-URL sonst eine Vorschau entfalten würde. Inline-Link-Vorschauen stören in einem On-Call-Thread.

Beide Transporte werden mit demselben Backoff wiederholt: 1s, 5s, 30s, 5min, 30min. Nach fünf Fehlern wird die Integration automatisch pausiert und eine E-Mail gesendet. Jeder Versuch wird in ClickHouse protokolliert und ist über den Observability-Guide abfragbar.

Schweregrad-zu-Farbe-Zuordnung

Farbe ist das einzige Signal, das Discord-Nutzer auf einen Blick erkennen. Wir haben vier Schweregrade gewählt und halten diese konsistent über alle Integrationen mit Farbunterstützung:

• info (#3B82F6, Blau) - neuer Link via API erstellt, erster Scan eines Ziels, Bio-Seite veröffentlicht. Nicht handlungsrelevant, nur zur Information.
• success (#22C55E, Grün) - Link-Checker erholt, Zertifikat für eine Custom Domain erneuert, Conversion-Schwelle erreicht.
• warn (#F59E0B, Bernstein) - Klickrate ist 3x über dem 7-Tage-Basiswert, Redirect-Chain wuchs von 2 auf 4 Hops, QR-Scan-Velocity um 80% gesunken. Ein menschlicher Blick lohnt sich.
• error (#EF4444, Rot) - broken_link, scan_failure (Google Safe Browsing hat das Ziel markiert), Custom Domain TLS abgelaufen, Webhook-Dispatcher nach 5 Versuchen aufgegeben.

Telegram rendert keine Farben, daher stellen wir der Nachricht ein Emoji voran, das dem Schweregrad entspricht: blauer Diamant, grünes Häkchen, gelbes Warnzeichen, rotes Kreuz. Gleiche Semantik, anderer Transport. Wer Telegram-Benachrichtigungen im Client auf rote Ereignisse filtern möchte, sucht nach dem Kreuz-Emoji im Text.

Häufige Fehlerfälle (und wie man sie erkennt)

In der Produktion treten drei Probleme auf. Sie lassen sich leicht beheben, wenn man weiß, wonach man suchen muss.

Discord-Rate-Limit bei einem geschwätzigen Webhook. Discord begrenzt jede Webhook-URL auf 50 Anfragen pro Sekunde und ca. 30/Minute dauerhaft. Wenn du einen Webhook für jeden click_threshold einer viralen Kampagne konfigurierst, wirst du das Limit überschreiten. Symptome: Benachrichtigungen kommen in Batches mit 30-60 Sekunden Abstand, 429-Antworten im Integrationsprotokoll. Lösung: Aktiviere das Ereignis-Throttle (standardmäßig deaktiviert), um innerhalb von 10 Sekunden ausgelöste Ereignisse in einem Embed zusammenzufassen.

Telegram-Bot-Datenschutzmodus. Der Datenschutzmodus ist für neue Bots standardmäßig aktiviert und betrifft nur, welche Nachrichten der Bot in Gruppen lesen kann. Ausgehende sendMessage-Aufrufe sind davon nicht betroffen. Der eigentliche Fallstrick: Wenn du den Bot einer Gruppe hinzufügst, muss er mindestens eine Nachricht empfangen, bevor getUpdates die chat_id zurückgibt. Wenn "Chats suchen" leer bleibt, sende dem Bot eine beliebige Nachricht und versuche es erneut. Bei Kanälen (nicht Gruppen) füge den Bot als Admin mit Posting-Rechten hinzu - kein Nachricht-zuerst-Tanz erforderlich.

Token-Rotation. Beide Transporte speichern das Geheimnis über die Envelope-Verschlüsselungsschicht aus ADR-0036 verschlüsselt. Klartext landet niemals in Postgres oder Protokollen. Wenn ein Token kompromittiert wird (Screenshot in Slack, Discord-Audit-Log-Eintrag, der nicht existieren sollte), sind es zwei Klicks: Widerruf beim Anbieter, neuen Wert in Elido einfügen. Die Integrationszeile, Ereignisfilter und ClickHouse-Verlauf bleiben erhalten, da sie an der Integrations-UUID hängen, nicht am Secret.

Wann welches Tool wählen

Wenn dein Team in Discord lebt, nutze Discord. Das Embed-Format ist reichhaltiger, die Inline-Felder werden auf Desktop und Mobile zuverlässig gerendert, und du erhältst Farbschweregrade kostenlos.

Wenn dein Team Telegram nutzt (verbreitet bei europäischen Ops-Teams, Entwicklerteams in Osteuropa und krypto-affinen Produkten), nutze Telegram. Die getUpdates- und sendMessage-API ist denkbar einfach, und der HTML-Modus deckt 95% der Formatierungsanforderungen ab.

Wenn du beides brauchst, nutze beides. Jede Integration ist eine eigene Zeile mit eigenem Ereignisfilter, sodass du error-Ereignisse nach Discord und Warnungen an eine Telegram-"Hintergrundrauschen"-Gruppe routen kannst. Einige unserer Kunden machen genau das.

Für alles außerhalb von Chat - CRM-Updates, Marketing-Automatisierung, BI-Pipelines - sind Zapier und die Webhooks-API die richtigen Werkzeuge. Chat ist für Menschen, die auf Ereignisse reagieren. Webhooks sind für Systeme, die auf Ereignisse reagieren.

Wofür du diese nicht verwenden solltest

Nutze Discord oder Telegram nicht als einzigen Link-Rot-Monitor. Chat ist flüchtig. Wenn die Benachrichtigung während eines hektischen Launches vorbeirauscht, findest du sie nicht wieder. Verwende Chat als hochsignalstarke Schicht über einem echten Observability-Stack: Elido's Link-Checker für synthetische Prüfungen, Datadog oder Sentry für Traces, und Chat für Ereignisse, die ein Mensch wirklich sehen muss.

Schreibe keine personenbezogenen Daten in Alert-Payloads. Der Standard-Payload enthält den Link-Slug und die Workspace-ID, niemals die Klick-IP oder den Besucher-Identifier. Wenn du über die API benutzerdefinierte Metadaten anhängst und diese personenbezogene Daten enthalten, landen sie im Discord- oder Telegram-Chatverlauf. Keiner der Anbieter steht auf der DPA-Liste der meisten Unternehmen. Bleib bei operativen Daten.

Was auf der Roadmap steht

Auto-Provisioning für Discord wäre möglich, wenn wir als Discord-Bot statt als Webhook-Konsument auftreten. Wir haben es prototypisiert. Der Schlüssel liegt darin, Nutzern zu ermöglichen, dem Elido-Bot mit einem OAuth-ähnlichen Consent-Flow Zugriff auf einen Kanal zu gewähren, woraufhin wir den Webhook serverseitig erstellen. Das steht nicht auf dem Plan des nächsten Quartals, würde Discord aber auf Live heben.

Für Telegram gibt es keinen sauberen Weg. BotFather ist eine rein menschliche Oberfläche, vollständiges Auto-Provisioning scheidet daher aus. Roadmap-Updates gibt es im Changelog.

Benötigst du eine Chat-Plattform, die wir noch nicht unterstützen (Mattermost? Microsoft Teams via Power Automate?), melde dich beim Team unter /about. Pläne und Seat-Limits findest du auf der Preisseite; Discord und Telegram sind im Pro-Plan und darüber enthalten.