n8n Telegram Trigger: Warum er scheitert und was hilft
Der n8n Telegram Trigger meldet bad webhook, wartet endlos oder läuft nur im Test? So lesen Sie mit getWebhookInfo, was Telegram gespeichert hat, und beheben die Ursache.
Warum der n8n Telegram Trigger scheitert: die kurze Antwort
Der n8n Telegram Trigger empfängt Nachrichten nur über einen Webhook. Das ist eine öffentliche HTTPS-Adresse, die Telegram selbst aufruft. Fast jeder Fehler mit diesem Node hat deshalb eine von drei Ursachen. Erstens meldet n8n Telegram eine falsche oder unverschlüsselte URL. Zweitens blockiert der Reverse Proxy die Websocket-Verbindung zum Editor. Drittens überschreiben sich Test- und Produktions-Workflow gegenseitig den einzigen Webhook des Bots. Mit einem einzigen curl-Aufruf an die Bot API sehen Sie, welche Ursache bei Ihnen zutrifft.
n8n beschreibt genau diese drei Probleme auf der offiziellen Seite „Common issues“ zum Telegram Trigger. Dieser Artikel zitiert die Seite und ergänzt, was dort fehlt: warum localhost nie funktioniert, wie Sie mit getWebhookInfo prüfen, was Telegram wirklich gespeichert hat, wann deleteWebhook hilft und was es mit Polling auf sich hat.
Für welche n8n-Version dieser Artikel gilt
Geschrieben ist der Artikel gegen n8n 2.48.7. Das ist laut den Release Notes die aktuelle stable-Version, Stand 20. November 2026. Die Beta steht bei 2.49.3. n8n 3.0.0 gibt es laut Dokumentation als „early access release“. Einen Termin für die allgemeine Verfügbarkeit nennen weder die Seite zu den Breaking Changes von 3.0 noch die Release Notes. Prüfen Sie vor einem Upgrade deshalb selbst die Seite „v3.0 breaking changes“.
Für dieses Thema ist eine Änderung in 3.0 wichtig: n8n 3.0 unterstützt keine Installation mehr über npm oder npx n8n. Sie brauchen also Docker. Zu WEBHOOK_URL, N8N_WEBHOOK_URL, N8N_PROXY_HOPS, dem Push-Backend oder den Telegram-Nodes nennt die Breaking-Changes-Seite dagegen keine Änderung.
Wie der Telegram Trigger überhaupt Nachrichten empfängt
Telegram kennt zwei Wege, auf denen ein Bot seine Updates bekommt. Beim ersten fragt der Bot selbst nach, mit getUpdates (Long Polling). Beim zweiten schickt Telegram jedes Update per HTTPS-POST an Ihren Server (Webhook). Die Bot API nennt beide Wege ausdrücklich „mutually exclusive“. Solange ein Webhook gesetzt ist, funktioniert getUpdates nicht.
Der Telegram Trigger von n8n nutzt nur den zweiten Weg. Wir haben den Quellcode des Nodes am 20. November 2026 auf dem Branch master gelesen. Beim Veröffentlichen des Workflows ruft n8n dort die Methode setWebhook auf, beim Zurückziehen deleteWebhook. Eine Polling-Methode hat der Node nicht. Beim Registrieren schickt n8n außerdem ein secret_token mit. Telegram sendet diesen Wert danach in jedem Webhook-Aufruf im Header X-Telegram-Bot-Api-Secret-Token zurück. Stimmt der Header nicht, antwortet der Node in aktuellen Versionen mit 403 und dem Text Provided secret is not valid.
Daraus folgt alles Weitere. n8n muss Telegram eine Adresse nennen, die Telegram aus dem Internet erreicht. Und pro Bot kann es nur eine solche Adresse geben.
Warum localhost den Telegram-Webhook nie empfangen kann
Telegram stellt an jede Webhook-Adresse feste Anforderungen. Laut Bot API und Telegrams Webhook-Leitfaden gilt:
- Die URL muss HTTPS verwenden. Ein Webhook über reines HTTP ist nicht möglich.
- Erlaubt sind nur die Ports 443, 80, 88 und 8443. Andere Ports funktionieren nicht.
- Der Server muss TLS 1.2 oder neuer sprechen.
- Webhooks laufen nur über IPv4. IPv6 wird für Webhooks derzeit nicht unterstützt.
- Weiterleitungen (Redirects) werden nicht unterstützt.
- Das Zertifikat muss gültig sein, und sein CN muss genau zur Domain passen. Ein selbst signiertes Zertifikat müssen Sie beim Aufruf von
setWebhookhochladen. - Die Anfragen kommen aus den Netzen
149.154.160.0/20und91.108.4.0/22. Telegram weist darauf hin, dass sich diese Bereiche ändern können.
Eine Adresse wie http://localhost:5678 verletzt gleich mehrere dieser Regeln. Sie ist kein HTTPS, und der Port ist nicht erlaubt. Vor allem zeigt localhost aus Sicht von Telegram auf Telegrams eigenen Rechner, nicht auf Ihren. Dasselbe gilt für jede private Adresse wie 192.168.x.x hinter Ihrem Router: Die Server von Telegram können sie nicht erreichen. Wörtlich steht das nicht in Telegrams Doku. Es folgt aber direkt aus den Anforderungen oben.
Sie haben zwei saubere Wege. Der erste ist ein VPS mit öffentlicher IPv4-Adresse, einer Domain und einem Reverse Proxy mit Let's-Encrypt-Zertifikat. Wie das mit Docker Compose aussieht, zeigt die Anleitung n8n mit Docker und HTTPS auf einem VPS selbst hosten. Der zweite ist ein Tunnel, der eine öffentliche HTTPS-Adresse auf Ihre lokale Instanz weiterleitet, etwa ein Cloudflare Tunnel ohne offene Ports. Prüfen Sie bei jedem Tunnel in dessen eigener Doku, welche Ports und Zertifikate er nach außen anbietet. Die Regeln von Telegram gelten für die öffentliche Seite des Tunnels.
Fehler 1: „bad webhook: An HTTPS URL must be provided“
Beim Testen oder Veröffentlichen erscheint diese Meldung:
Bad request: bad webhook: An HTTPS URL must be provided for webhookDer Text stammt nicht von n8n. Er ist die Antwort der Telegram-API auf setWebhook, weil n8n eine URL ohne HTTPS geschickt hat. Die Common-issues-Seite von n8n sagt dazu: „This error occurs when you run n8n behind a reverse proxy and there is a problem with your instance's webhook URL.“
Den Mechanismus erklärt n8ns Seite zur Webhook-URL hinter einem Reverse Proxy. Ohne eigene Einstellung baut n8n die Webhook-URL aus N8N_PROTOCOL, N8N_HOST und N8N_PORT zusammen. Die Standardwerte sind http, localhost und 5678. n8n meldet Telegram also eine Adresse, die mit http://localhost:5678 beginnt, und Telegram lehnt sie sofort ab. Hinter einem Proxy hilft auch ein korrekter Hostname allein nicht. n8n läuft intern auf Port 5678, der Proxy bedient nach außen aber Port 443.
Die Lösung laut n8n: TLS am Reverse Proxy beenden und danach die öffentliche HTTPS-Adresse als Webhook-URL eintragen.
WEBHOOK_URL oder N8N_WEBHOOK_URL?
Hier ist die Dokumentation nicht einheitlich. Die Telegram-Seite nennt noch WEBHOOK_URL. Die Seite zum Reverse Proxy und die Referenz der Umgebungsvariablen nennen N8N_WEBHOOK_URL. Beides stimmt, je nach Version:
N8N_WEBHOOK_URLgibt es ab n8n 2.30.0.- Ab n8n 2.35.0 ist
WEBHOOK_URLveraltet. Die Variable funktioniert weiter als Alias, aber n8n schreibt beim Start eine Deprecation-Warnung ins Log. - Auf einem Image vor 2.30.0 gibt es nur
WEBHOOK_URL.
Für 2.48.7 setzen Sie also N8N_WEBHOOK_URL. Einen Standardwert hat die Variable nicht. Fehlt sie, gilt die Zusammensetzung aus Protokoll, Host und Port von oben. Der passende Ausschnitt aus der Compose-Datei sieht so aus (Domain anpassen):
services:
n8n:
environment:
- N8N_HOST=n8n.example.com
- N8N_PORT=5678
- N8N_PROTOCOL=https
- N8N_WEBHOOK_URL=https://n8n.example.com/
- N8N_PROXY_HOPS=1
ports:
- "127.0.0.1:5678:5678"Die offizielle Compose-Anleitung von n8n setzt dieselben Werte für Host, Port, Protokoll und Webhook-URL. Sie bindet n8n ebenfalls nur an 127.0.0.1:5678. Welche n8n-Version Sie fahren, legt das Image-Tag fest. Prüfen Sie auf Docker Hub, welche Tags es für n8nio/n8n gibt, bevor Sie eines festschreiben.
N8N_PROXY_HOPS=1 stammt aus n8ns Seite zum Reverse Proxy. Es sagt n8n, dass genau ein Proxy davor sitzt. Dazu soll der letzte Proxy die Header X-Forwarded-For, X-Forwarded-Host und X-Forwarded-Proto weitergeben. Den HTTPS-Fehler von Telegram behebt diese Variable aber nicht. Das erledigt allein die richtige Webhook-URL.
Übernehmen Sie die Änderung und prüfen Sie, was im Container wirklich ankommt:
docker compose up -d
docker compose exec n8n printenv N8N_WEBHOOK_URL WEBHOOK_URL
docker compose logs n8n 2>&1 | grep -i deprecatprintenv sollte genau eine Zeile mit Ihrer https://-Adresse ausgeben. Erscheint auch ein Wert für WEBHOOK_URL, kommt er meist aus einer alten .env-Datei oder einem älteren Compose-Block. Entfernen Sie ihn, damit nur eine Quelle gilt. Der grep zeigt, ob n8n noch eine Deprecation-Warnung schreibt.
Danach muss der Trigger seinen Webhook neu anmelden. Ziehen Sie den Workflow in n8n zurück und veröffentlichen Sie ihn wieder. Dabei ruft der Node erst deleteWebhook und dann setWebhook mit der neuen Adresse auf.
Fehler 2: „Waiting for trigger event“ hängt endlos
Sie klicken im Editor auf Execute step oder Execute workflow und schreiben dem Bot eine Nachricht. Der Node wartet trotzdem weiter. Die n8n-Doku nennt als Ursache: „this behavior often occurs when you run n8n behind a reverse proxy without configuring websocket proxying.“ Sie empfiehlt, im Proxy die Websocket-Unterstützung einzuschalten, und nennt dabei Nginx, Caddy, Apache HTTP Server und Traefik.
Der Hintergrund: Der Editor bekommt Änderungen vom Server über eine dauerhafte Verbindung. Laut Referenz der Umgebungsvariablen ist das Push-Backend standardmäßig websocket (Variable N8N_PUSH_BACKEND). Die Alternative ist sse (Server-Sent Events). Kommt die Websocket-Verbindung nicht durch, kann die Nachricht von Telegram durchaus bei n8n eingehen. Nur der Editor erfährt nichts davon. Ob ein Wechsel auf sse dieses Problem löst, sagt die Doku nicht. Reparieren Sie deshalb lieber den Proxy.
Bei Nginx tritt das Problem fast sicher auf. Die Nginx-Doku erklärt, dass Upgrade ein Hop-by-Hop-Header ist. Nginx reicht ihn deshalb nicht vom Client zum Backend weiter, und Sie müssen diese Header ausdrücklich setzen. n8n liefert dafür kein fertiges Snippet. Der folgende Block ist unsere eigene Konfiguration, aufgebaut nach dem Beispiel aus der Nginx-Doku:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name n8n.example.com;
ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:5678;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
}
}Der map-Block muss im http-Kontext stehen. Ob Ihre Site-Datei innerhalb von http eingebunden wird, zeigt grep -n sites-enabled /etc/nginx/nginx.conf. Steht die include-Zeile im http-Block, darf map ganz oben in der Site-Datei stehen. proxy_http_version 1.1 ist laut Nginx-Doku vor Version 1.29.7 nötig. proxy_read_timeout ist wichtig, weil Nginx eine Websocket-Verbindung standardmäßig schließt, wenn 60 Sekunden lang keine Daten vom Backend kommen. Was die einzelnen Direktiven tun, erklärt unsere Erklärung der Nginx-Reverse-Proxy-Konfiguration ausführlich.
sudo nginx -t && sudo systemctl reload nginxnginx -t sollte syntax is ok und test is successful melden. Öffnen Sie danach den Editor und die Entwicklertools des Browsers, Reiter Network. Filtern Sie dort auf Websocket-Verbindungen. Eine gesunde Verbindung zeigt den Status 101. Fehlt die Verbindung oder bricht sie ab, kommt der Upgrade-Header noch nicht durch.
Zu Caddy sagt die Doku von reverse_proxy, dass der Proxy Websocket-Verbindungen unterstützt. Eine Zusatzoption dafür nennt sie nicht. Bei Traefik, das n8ns eigene Compose-Anleitung verwendet, prüfen Sie im Zweifel die Traefik-Doku. Liegt vor Ihrem Proxy noch ein CDN oder ein Tunnel, muss auch dieser Websockets durchlassen.
Fehler 3: Der Bot läuft nur im Test oder nur in Produktion
Die n8n-Doku ist hier eindeutig: „Telegram only allows you to register a single webhook per app.“ n8n hat aber zwei Webhook-URLs pro Trigger. Die Test-URL meldet n8n an, wenn Sie Listen for Test Event oder Execute workflow wählen und der Workflow nicht aktiv ist. Die Produktions-URL meldet n8n an, wenn Sie den Workflow veröffentlichen. Jeder Wechsel überschreibt bei Telegram die vorherige Adresse. Telegram schickt dann nur noch an eine der beiden URLs. Die andere bekommt kein Update mehr.
Ein typischer Ablauf: Der Workflow ist veröffentlicht und läuft. Sie testen kurz im Editor. Ab jetzt zeigt der Bot auf die Test-URL, und der Produktions-Workflow bleibt stumm, ohne Fehlermeldung. In der Standardkonfiguration liegen Test-Webhooks unter dem Pfad webhook-test und Produktions-Webhooks unter webhook (Variablen N8N_ENDPOINT_WEBHOOK_TEST und N8N_ENDPOINT_WEBHOOK). Am Pfad in getWebhookInfo sehen Sie also sofort, welche Seite gerade registriert ist.
Der Quellcode des Nodes nennt dieselbe Grenze für mehrere Workflows: „you can use just one Telegram trigger for each bot at a time“. Zwei veröffentlichte Workflows mit Telegram Trigger am selben Bot stören sich also genauso.
n8n nennt zwei Auswege:
- Ein zweiter Bot nur zum Testen. Bei BotFather legen Sie mit
/newboteinen weiteren Bot an. Sein Benutzername muss aufbotenden. Dessen Token tragen Sie als Access Token in eine eigene Telegram-Credential in n8n ein. Test und Produktion nutzen dann getrennte Webhooks. Das ist der richtige Weg für jeden Bot, den echte Nutzer verwenden. - Den Workflow zum Testen zurückziehen. Die Doku warnt selbst: Dieser Weg schaltet Ihren Produktions-Workflow für die Dauer des Tests ab. Danach müssen Sie ihn wieder veröffentlichen.
Was Telegram wirklich registriert hat: getWebhookInfo
Die Bot API beantwortet die wichtigste Frage direkt. getWebhookInfo braucht keine Parameter. Die Methode zeigt die gespeicherte URL, die Zahl wartender Updates und den letzten Zustellfehler. Der Token Ihres Bots steht dabei in der URL. Lesen Sie ihn deshalb verdeckt ein, damit er nicht in der Shell-History landet. Kopieren Sie die Ausgabe auch nicht in öffentliche Foren.
read -rsp 'Bot-Token: ' TG_TOKEN; echo
curl -s "https://api.telegram.org/bot${TG_TOKEN}/getWebhookInfo" | python3 -m json.toolEine Antwort kann etwa so aussehen. Das Beispiel ist erfunden und gekürzt. Die Feldnamen stammen aus der Bot API, der Fehlertext dient nur zur Veranschaulichung:
{
"ok": true,
"result": {
"url": "https://n8n.example.com/webhook-test/1a2b3c/webhook",
"has_custom_certificate": false,
"pending_update_count": 3,
"last_error_date": 1763630000,
"last_error_message": "Wrong response from the webhook: 502 Bad Gateway",
"max_connections": 40,
"ip_address": "203.0.113.10"
}
}So lesen Sie die Felder:
urlist leer: Es ist kein Webhook gesetzt. Entweder ist der Workflow nicht veröffentlicht, oder das Registrieren ist gescheitert. Suchen Sie im n8n-Log nach derbad webhook-Meldung.urlenthältwebhook-test: Die Test-URL hat die Produktion überschrieben. Veröffentlichen Sie den Workflow neu.urlzeigt auf einen alten Host oder eine alte Domain: Der Webhook stammt aus einer früheren Installation. Das ist ein Fall fürdeleteWebhook.pending_update_countsteigt: Updates warten auf die Zustellung. Telegram erreicht Ihren Webhook offenbar nicht erfolgreich.last_error_messageundlast_error_date: der letzte Fehler bei der Zustellung, mit Unix-Zeitstempel. Relevant ist nur ein Fehler, der nach Ihrer letzten Änderung liegt.ip_address: die IP, die Telegram für Ihren Webhook gerade verwendet. Weicht sie von der IPv4-Adresse Ihres VPS ab, prüfen Sie den A-Record Ihrer Domain.
Den Zeitstempel rechnen Sie so in lokale Zeit um:
date -d @1763630000Ein Fehler mit 502 bedeutet, dass Telegram Ihren Proxy erreicht, der Proxy aber n8n nicht. Prüfen Sie dann, ob der Container läuft. Fällt n8n selbst immer wieder aus, hilft unsere Anleitung für den Fall, dass n8n ständig offline geht.
Wann Sie deleteWebhook aufrufen sollten
deleteWebhook entfernt den Webhook, damit der Bot wieder getUpdates nutzen kann. n8n ruft die Methode beim Zurückziehen eines Workflows selbst auf. Von Hand brauchen Sie sie nur, wenn ein Webhook übrig geblieben ist: von einer alten Domain, einem gelöschten Workflow oder einer Instanz, die es nicht mehr gibt.
curl -s "https://api.telegram.org/bot${TG_TOKEN}/deleteWebhook"Bei Erfolg antwortet die API mit "result": true. Hängen Sie ?drop_pending_updates=true an die URL an, verwirft Telegram zusätzlich alle wartenden Updates. Das ist sinnvoll, wenn sich alte Nachrichten angestaut haben, die Ihr Workflow nicht mehr verarbeiten soll. Achtung: Ist gerade ein Produktions-Workflow veröffentlicht, empfängt er danach nichts mehr, bis Sie ihn neu veröffentlichen. Prüfen Sie anschließend mit getWebhookInfo, dass url leer ist. Veröffentlichen Sie dann den richtigen Workflow.
Telegram ohne Webhook: geht Polling in n8n?
Mit dem Telegram Trigger geht es nicht, denn laut Quellcode kennt der Node nur den Webhook-Weg. Wer keine öffentliche HTTPS-Adresse hat, kann Polling nur selbst bauen. Ein Beispiel wäre ein zeitgesteuerter Workflow, der getUpdates über einen HTTP-Request aufruft. Das ist von n8n nicht dokumentiert, und wir haben es nicht getestet. Bevor Sie es versuchen, sollten Sie die Regeln der Bot API kennen:
getUpdatesfunktioniert nicht, solange ein Webhook gesetzt ist. Rufen Sie also zuerstdeleteWebhookauf, und veröffentlichen Sie keinen Telegram Trigger am selben Bot.- Ein Update gilt erst als bestätigt, wenn Sie
getUpdatesmit einemoffsetaufrufen, der höher ist als seineupdate_id. Ohne Offset bekommen Sie dieselben Nachrichten immer wieder. limitakzeptiert Werte von 1 bis 100, Standard ist 100.timeoutsteht standardmäßig auf 0, also auf kurzem Polling.- Telegram hält nicht abgeholte Updates höchstens 24 Stunden vor.
In den meisten Fällen ist ein Tunnel oder ein kleiner VPS mit Domain einfacher als selbst gebautes Polling. Dann funktioniert der fertige Trigger so, wie n8n ihn vorgesehen hat.
Checkliste in der richtigen Reihenfolge
- Ist n8n über IPv4 unter einer öffentlichen HTTPS-Adresse auf Port 443, 80, 88 oder 8443 erreichbar, mit gültigem Zertifikat?
- Zeigt
printenv N8N_WEBHOOK_URLim Container genau diesehttps://-Adresse? - Lässt der Proxy Websockets durch (Status
101im Browser)? - Zeigt
getWebhookInfodie Produktions-URL mitwebhookstattwebhook-test? - Ist
last_error_messageleer oder älter als Ihre letzte Änderung? - Nutzen Test und Produktion getrennte Bots?
FAQ
Warum meldet Telegram „bad webhook: An HTTPS URL must be provided“?
n8n hat Telegram eine Webhook-URL ohne HTTPS gemeldet. Ohne N8N_WEBHOOK_URL baut n8n die URL aus N8N_PROTOCOL, N8N_HOST und N8N_PORT, standardmäßig also aus http, localhost und 5678. Telegram nimmt nur HTTPS-Adressen an. Beenden Sie TLS am Reverse Proxy und setzen Sie N8N_WEBHOOK_URL auf die öffentliche https://-Adresse. Vor n8n 2.30.0 heißt die Variable WEBHOOK_URL. Veröffentlichen Sie den Workflow danach neu.
Kann ich den n8n Telegram Trigger auf localhost testen?
Nicht direkt. Telegram ruft den Webhook von eigenen Servern auf und verlangt HTTPS, ein gültiges Zertifikat, IPv4 und einen der Ports 443, 80, 88 oder 8443. Eine Adresse auf localhost oder in Ihrem Heimnetz erreichen diese Server nicht. Nutzen Sie einen VPS mit Domain oder einen Tunnel, der eine öffentliche HTTPS-Adresse auf Ihre lokale Instanz weiterleitet.
Warum funktioniert mein Telegram-Bot nur im Test, aber nicht nach dem Veröffentlichen?
Telegram speichert pro Bot nur einen Webhook. Jeder Test im Editor meldet die Test-URL an und überschreibt damit die Produktions-URL, und umgekehrt. Prüfen Sie mit getWebhookInfo, ob die gespeicherte URL webhook-test enthält. Die saubere Lösung ist ein zweiter Bot nur für Tests. Alternativ ziehen Sie den Workflow während des Tests zurück und veröffentlichen ihn danach neu.
Heißt die Variable WEBHOOK_URL oder N8N_WEBHOOK_URL?
N8N_WEBHOOK_URL gibt es ab n8n 2.30.0, und ab 2.35.0 ist WEBHOOK_URL veraltet. Der alte Name funktioniert weiter als Alias, n8n schreibt aber beim Start eine Deprecation-Warnung. Die Telegram-Seite der n8n-Doku nennt noch den alten Namen. Auf aktuellen Versionen wie 2.48.7 setzen Sie N8N_WEBHOOK_URL. Auf Images vor 2.30.0 gibt es nur WEBHOOK_URL.
Kann der n8n Telegram Trigger Polling statt Webhook nutzen?
Nein. Laut seinem Quellcode registriert der Node nur einen Webhook über setWebhook. Telegram erlaubt getUpdates außerdem nur, solange kein Webhook gesetzt ist. Polling müssten Sie selbst bauen, mit deleteWebhook, einem zeitgesteuerten Workflow und getUpdates mit offset. Ein Tunnel ist meist der einfachere Weg.