Telegram-Bots und Mini-Apps auf Localhost: setWebhook, der Secret-Token-Header und die neue Origin-Check
Telegram-Bots und Mini-Apps auf Localhost betreiben: setWebhook konfigurieren, den Secret-Token-Header prüfen und die Origin-Check von Bot API 10.2 bestehen. Tipps für stabile Tunnel.

Quick answer
Telegram-Bots und Mini-Apps auf Localhost: Webhook-Guide 2026: webhook testing answer
For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.
How do I test webhooks on localhost?
Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.
Why does a stable webhook URL matter?
Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.
Telegram kann Updates nur an eine öffentliche HTTPS-Adresse liefern, und localhost ist keine davon. Seit dem 20. Juli 2026 gibt es eine zweite Einschränkung für Mini Apps. Telegram blockiert jetzt Methoden von Mini Apps, wenn sie von einer anderen Origin stammen als die eigene Domain der Mini App. Zusammen machen diese beiden Tatsachen Ihre Tunnel-URL zu einem erstklassigen Konfigurationspunkt, nicht zu einer Nebensache.
Diese Anleitung deckt die Entwicklung eines Telegram-Bots und einer Mini-App auf einem lokalen Rechner ab:
- Registrierung des Webhooks mit
setWebhook - Authentifizierung von Anfragen mit dem Secret-Token-Header
- Umgang mit unbekannten Update-Feldern, ohne erneute Versuche auszulösen
- Validierung von Mini App
initData - Verständnis, was die neue Origin-Check für eine Entwicklungsumgebung bedeutet
Was hat sich in Bot API 10.2 geändert (und was wurde seitdem ausgeliefert)
Telegram veröffentlichte Bot API 10.2 am 14. Juli 2026. Laut dem offiziellen Changelog hat diese Veröffentlichung auch die Sicherheit der Mini Apps erhöht, indem Methoden von Origins außerhalb der ursprünglichen Mini App-Domain nicht mehr zulässig sind. Der Schutz wurde automatisch für alle Mini Apps am 20. Juli 2026 aktiviert. Bots können sich über die BotFather Mini App abmelden. Das Abmelden bedeutet, Verantwortung dafür zu übernehmen, dass die Mini App keine Links zu untrustworthy Seiten hat. Telegrams BotNews-Kanal kündigte die Änderung als Warnung an: Externe Websites, die aus Links innerhalb einer Mini App geöffnet werden, können standardmäßig nicht mehr Mini App-Methoden verwenden.
Weitere 10.2-Ergänzungen sind erwähnenswert, weil sie in Ihren Webhook-Payloads erscheinen:
- Ephemeral messages: neue Bearbeitungs- und Löschmethoden, plus
receiver_userundephemeral_message_idinMessage. - Rich messages:
InputRichMessageerhieltblocksundmedia-Felder. - Communities: ein neuer Typ
Community,community_chat_addedundcommunity_chat_removedService-Nachrichten, und eincommunity-Feld inChatFullInfo. - Subscriptions: ein neues Top-Level-Feld
subscriptioninUpdate, das einBotSubscriptionUpdated-Objekt trägt.
Die Bot API hat sich seither weiterbewegt:
- Bot API 10.3 (24. August 2026):
- Knöpfe in Rich Messages
- Deaktivierte Inline-Buttons
- Ephemeral-Message-Parameter in ein einziges Objekt
ephemeral_message_parameterszusammengeführt - Ein nativer Stop-Button für gestreamte Entwürfe
- Ein neues
stopped_message_generation-Feld inUpdate
- Bot API 10.4 (9. November 2026):
- HTML-Widgets über
sendWidget,sendSharedWidget,answerWidgetQuery,editMessageWidgetDataundeditSharedWidgetData - TON-Wallet-Karten und Transferdienstnachrichten
- Ephemere Antworten, ausgelöst durch Button-Drücke
- Laut Release Notes der Bibliothek neue Typen
widget_queryundshared_widget_query
- HTML-Widgets über
Keines der 10.2–10.4-Ankündigungen ändert, wie setWebhook oder der Secret-Token-Header funktionieren. Das Update-Objekt erhält weiterhin Top-Level-Felder, weshalb Schritt 3 wichtig ist.
Warum localhost für Telegram-Webhooks nicht funktioniert
Ein Webhook ist eine ausgehende HTTPS-POST von den Servern von Telegram zu Ihrer URL. Telegram kann http://localhost:3000 nicht erreichen, daher benötigen Sie einen öffentlichen HTTPS-Endpunkt, der auf Ihren Rechner weiterleitet. Die dokumentierten Anforderungen von Telegram:
- Die URL muss HTTPS sein.
- Unterstützte Webhook-Ports sind 443, 80, 88 und 8443.
- Solange ein Webhook gesetzt ist, können Sie Deliveries nicht über
getUpdatesempfangen. - Ein selbst signiertes Zertifikat erfordert das Hochladen des öffentlichen Zertifikats über den Parameter
certificate, was in der Entwicklung selten sinnvoll ist. - Laut Hookdeck-Zusammenfassung zu Telegrams Webhook-Führung ist die Lieferung IPv4-only und benötigt TLS 1.2 oder später.
- Nicht zugestellte Updates werden nicht länger als 24 Stunden gespeichert.
Ein Tunnel erfüllt all dies auf einmal. Er gibt Ihnen einen öffentlichen Hostname mit gültigem Zertifikat auf Port 443 und leitet Verkehr an einen lokalen Port wie 3000 weiter.
Es gibt eine Ausnahme nur für die Bot-Seite. Wenn Sie den Open-Source-Server telegram-bot-api lokal ausführen, dokumentiert Telegram, dass Ihr Bot eine HTTP-Webhook-URL, jede lokale IP-Adresse und jeden Port verwenden kann. Damit entfällt der Tunnel für die Webhook-Zustellung. Er macht eine Mini App nicht erreichbar von einem Telefon, weil der Telegram-Client trotzdem die Mini App-URL laden muss.
Jeder Bot hat genau eine webhook-URL. Ein erneuter Aufruf von setWebhook ersetzt diese. Verwenden Sie einen separaten Entwicklungs-Bot, der über BotFather erstellt wird, damit Ihre Experimente keinen Produktionsverkehr umleiten.
Schritt 1: Registrieren des Webhooks mit setWebhook
Starten Sie Ihren lokalen Server, starten Sie Ihren Tunnel und registrieren Sie die öffentliche URL:
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-subdomain.example.com/telegram/webhook",
"secret_token": "'"$TELEGRAM_WEBHOOK_SECRET"'",
"allowed_updates": ["message", "callback_query"],
"drop_pending_updates": true
}'
Die Parameter, die Sie tatsächlich verwenden:
| Parameter | What it does |
|---|---|
url |
HTTPS-URL, die ein JSON-Serialisiertes Update pro POST empfängt. Ein leerer String entfernt den webhook. |
secret_token |
Secret, das bei jeder Anfrage im Header zurückgespielt wird. 1–256 Zeichen. |
allowed_updates |
Aktualisierungstypen, die empfangen werden sollen. Eine leere Liste bedeutet alle Typen außer chat_member, message_reaction und message_reaction_count. Falls angegeben, wird die vorherige Einstellung beibehalten. |
max_connections |
Maximale gleichzeitige HTTPS-Verbindungen für die Zustellung, 1–100, Standard 40. |
drop_pending_updates |
Verbleibende Nachlässe verwerfen, nützlich, wenn Sie einen Bot auf eine neue URL verschieben. |
ip_address |
Feste IP anstelle der DNS-Auflösung verwenden. |
certificate |
Öffentliches Zertifikat (hochgeladen als Datei) für selbstsignierte Setups. |
Zwei Gewohnheiten sparen Entwicklungszeit:
- Setzen Sie
drop_pending_updates, wenn Sie URLs ändern, damit Ihr lokaler Server nicht mit veralteten Nachrichten überschwemmt wird. - Rufen Sie
getWebhookInfoauf, wann immer Deliveries anhalten. Es meldet die aktuelle URL,pending_update_count,last_error_date,last_error_messageund die aktivenallowed_updates.
Eine Änderung von allowed_updates gilt nicht für Updates, die vor dem Aufruf erstellt wurden, sodass einige unerwünschte Updates dennoch ankommen können.
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"
Um wieder auf Polling umzusteigen, rufen Sie deleteWebhook auf.
Schritt 2: Das Secret-Token-Header überprüfen
Wenn Sie secret_token an setWebhook übergeben, enthält Telegram ihn in jeder Webhook-Anfrage im Header X-Telegram-Bot-Api-Secret-Token. Der Token muss 1 bis 256 Zeichen lang sein und darf nur A-Z, a-z, 0-9, _ und - enthalten.
Das ist wichtig, weil Ihre Tunnel-URL öffentlich ist. Ohne ein Secret kann jeder, der die URL entdeckt, gefälschte Updates posten, und in der Anfrage identifiziert Telegram nicht. Wenn Sie kein Token setzen, sendet Telegram gar keinen Header.
Der Mechanismus ist ein Shared Secret, kein Signatur-Verfahren. Nichts wird über den Body berechnet, also lässt ein geleaktes Secret einen Angreifer Requests fälschen, bis Sie es rotieren. Die Rotation ist einfach: Rufen Sie setWebhook erneut mit einem neuen Wert auf. Hookdeck’s Anleitung listet auch Telegrams veröffentlichte Source Ranges (149.154.160.0/20 und 91.108.4.0/22) als optionale zweite Ebene, und bemerkt, dass sie sich ändern können.
Ein minimales Express-Handler-Beispiel:
import express from "express";
import crypto from "node:crypto";
const SECRET = process.env.TELEGRAM_WEBHOOK_SECRET;
if (!SECRET) throw new Error("TELEGRAM_WEBHOOK_SECRET is not set");
const app = express();
app.use(express.json());
function secretMatches(received) {
const a = Buffer.from(received ?? "");
const b = Buffer.from(SECRET);
return a.length === b.length crypto.timingSafeEqual(a, b);
}
app.post("/telegram/webhook", (req, res) => {
if (!secretMatches(req.get("x-telegram-bot-api-secret-token"))) {
return res.sendStatus(401);
}
res.sendStatus(200); // acknowledge, then process
handleUpdate(req.body).catch(console.error);
});
app.listen(3000);
Drei Details lohnen sich zu kopieren:
- Die Überprüfung läuft in konstanter Zeit.
- Die Prüfung erfolgt, bevor irgendeine Logik den Body berührt.
- Der Handler schließt fehlschlagend, wenn das Secret nicht konfiguriert ist.
Telegram publiziert keine Antwortzeit, also Delivery nicht von langsamer Verarbeitung abhängig machen. Speichern oder queueen Sie das Update zuerst, geben Sie 200 zurück, dann verarbeiten Sie es. Wenn Sie 200 zurückgeben und dann abstürzen, ist das Update weg, speichern Sie es also, bevor Sie es bestätigen.
Schritt 3: Unknown-Felder tolerieren, damit Telegram nicht erneut sendet
Telegram behandelt jede Antwort außer 2xx als fehlende Zustellung. Es wiederholt die Anfrage und gibt nach einer als „angemessene Anzahl von Versuchen“ bezeichneten Zeit auf, ohne einen Plan zu veröffentlichen. Das hat eine scharfe Folge für strikte Parser. Wenn Ihr Handler ein Update ablehnt, weil es ein Feld enthält, das Sie nicht erkennen, sendet Telegram es erneut, und Ihre Logs füllen sich mit demselben Fehler.
Ein Update enthält update_id plus höchstens ein weiteres Feld, und die Menge dieser Felder wächst: managed_bot, guest_message, subscription, stopped_message_generation und in 10.4 auch Widget-Abfragen. Ein Decoder, der bei unerwarteten Keys scheitert, kann anfangen, Fehler zurückzugeben, obwohl an Ihrem Bot nichts falsch ist. Praktische Regeln:
- Parse die Felder, die du kennst, und ignoriere den Rest. In TypeScript mit Zod vermeide
.strict()in Webhook-Schemas. In Go vermeideDisallowUnknownFieldsim Decoder. In Rust mit serde füge nichtdeny_unknown_fieldszu Telegram-Typen hinzu. - Gib 200 zurück für Updates, die du nicht verarbeitest. Ein unsupported Update ist kein Fehler.
- Logge unbekannte Update-Kinds auf niedriger Ebene, damit du neue Features bemerkst, ohne die Zustellung zu brechen.
- Dedupliziere nach
update_id. Telegram dokumentiert es als Weg, doppelte Updates zu ignorieren und Ordnung wiederherzustellen. Nach einer Woche ohne Updates wird die nächste ID zufällig gewählt statt sequentiell, also verlasse dich nicht darauf, dass sie fortlaufend ist. - Pin deine Telegram-Bibliothek und lies ihre Release Notes, bevor du aktualisierst. Bibliotheken unterscheiden sich darin, wie schnell sie neue Bot API-Versionen abdecken, und manche fallen Update-Typen, die sie nicht kennen, still weg.
async function handleUpdate(update) { if (update.message) return onMessage(update.message); if (update.callback_query) return onCallback(update.callback_query); const kind = Object.keys(update).find((k) => k !== "update_id"); console.info("unhandled update kind:", kind); }
Verwenden Sie außerdem allowed_updates als zweite Schicht. Nur die Typen abonnieren, die Sie behandeln, damit unwichtige Ereignisse gar nicht erst ankommen.
Schritt 4: Eine Mini-App von localhost aus bedienen
Eine Mini-App ist eine Web-Seite, die im In-App-Browser von Telegram läuft und mit dem Client über window.Telegram.WebApp spricht. In der Entwicklung richten Sie sie auf Ihre Tunnel-URL aus:
- Starten Sie Ihren Frontend-Dev-Server auf einem lokalen Port.
- Starten Sie den Tunnel und notieren Sie den öffentlichen HTTPS-Hostnamen.
- Setzen Sie diese URL dort, wo Ihre Mini-App gestartet wird. Telegram dokumentiert mehrere Routen: ein
web_appInline- oder Tastatur-Button, der Bot-Menü-Button (BotFather’s/setmenubuttonoder Bot Settings → Menu Button), die Haupt-Mini-App in BotFather und direkte Links in der Formhttps://t.me/botusername/appname. - Öffnen Sie den Bot in Telegram und starten Sie die Mini-App.
Halten Sie den Hostnamen überall identisch. Die Origin-Check unten macht das mehr als Ordnung.
Produktion Mini-Apps werden über HTTPS bedient, was jeder Tunnel bietet. Telegrams separatere Testumgebung ist die Ausnahme. Sie verwendet ihr eigenes Konto und ihren eigenen Bot, und ihre Dokumentation erlaubt dort plain HTTP Mini-App-Links. Man ruft sie über https://api.telegram.org/bot<token>/test/METHOD_NAME auf.
Zwei Framework-Fallen treten immer wieder auf:
- Host checks. Der Dev-Server von Vite antwortet nur auf Anfragen mit dem Host-Header
localhost, einem Subdomain von.localhostoder einer IP-Adresse. Andernfalls kommt „Blocked request. This host is not allowed.“ Fügen Sie Ihren Tunnel-Hostnamen zuserver.allowedHostshinzu. Ein führender Punkt (.) entspricht Subdomains. Setzen Sie nichtallowedHosts: true, da das jeden Host-Header akzeptiert und den Dev-Server DNS-Rebinding aussetzt. - Hot reload. Der HMR WebSocket muss ebenfalls durch den Tunnel gehen. Hinter einem HTTPS-Tunnel müssen Sie eventuell
server.hmr.clientPortauf 443 setzen. Strapi führt dazu Hinweise, testen Sie es in Ihrer Konfiguration.
Um im Telegram-Client zu debuggen, dokumentiert Telegram diese Optionen:
- iOS: tippe das Settings-Symbol 10 Mal an und aktiviere Allow Web View Inspection, dann verwende das Entwicklermenü von Safari.
- Android: aktiviere WebView Debug in Telegrams Debug-Einstellungen, dann öffne
chrome://inspect/#devices. - Desktop: die Windows/Linux-Beta hat ein experimentelles Webview-Inspektions-Tool, und die macOS-Beta hat eine „Debug Mini Apps“-Option.
InitData auf Ihrem Server validieren
Wenn die Mini App geöffnet wird, enthält window.Telegram.WebApp.initData eine signierte Abfragezeichenfolge. Sie ist leer, wenn die Mini App von einer Tastatur-Schaltfläche oder dem Inline-Modus gestartet wurde. Vertrauen Sie niemals auf initDataUnsafe oder irgendein Benutzerobjekt auf dem Client. Senden Sie die rohe Zeichenkette an Ihr Backend und validieren Sie sie mit dem von Telegram dokumentierten Algorithmus:
- Entfernen Sie das Feld
hash. Lassen Sie jedes andere empfangene Feld, einschließlichsignature, das für Drittanbieter-Verifikation existiert. - Sortieren Sie die restlichen
key=value-Paarungen nach Schlüssel und verbinden Sie sie mit Zeilenumbrüchen (\n). - Berechnen Sie einen Secret-Key: HMAC-SHA256 des Bot-Tokens, wobei der konstante String
WebAppDataals Schlüssel verwendet wird. - Berechnen Sie den HMAC-SHA256 des Data-Check-Strings mit diesem Secret-Key, als Hex.
- Vergleichen Sie es mit
hashin konstanter Zeit und lehnen Sie ab, wennauth_dateveraltet ist.import crypto from "node:crypto"; function verifyInitData(initData, botToken, maxAgeSeconds = 3600) { const params = new URLSearchParams(initData); const hash = params.get("hash"); params.delete("hash"); const checkString = [...params.entries()] .sort(([a], [b]) => (a < b ? -1 : 1)) .map(([k, v]) => `${k}=${v}`) .join("\n"); const secret = crypto.createHmac("sha256", "WebAppData").update(botToken).digest(); const expected = crypto.createHmac("sha256", secret).update(checkString).digest("hex"); const valid = hash && hash.length === expected.length && crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected)); const fresh = Date.now() / 1000 - Number(params.get("auth_date")) <= maxAgeSeconds; return Boolean(valid && fresh); }
Telegram sagt nur, auth_date zu prüfen, um veraltete Daten zu vermeiden. Das eine-Stunde-Fenster ist Ihre Wahl. Wenn ein Drittanbieter die Daten ohne Token Ihres Bots validieren muss, bietet Telegram einen Ed25519 signature-Flow an, der Ihre Bot-ID und Telegrams öffentliche Schlüssel verwendet.
Die neue Mini-App-Origin-Check, erklärt
Vor dem 20. Juli 2026 konnte jede Seite, die in der WebView Ihrer Mini App geöffnet wurde, Telegram.WebApp.*-Methoden wie close(), expand(), dem Hauptknopf oder sendData() aufrufen. Jetzt dürfen diese Aufrufe nur noch von der eigenen Domain der Mini App stammen. Telegrams Changelog nennt es die „Original Mini App Domain“. Drittanbieter-Dokumentationen beschreiben es als Domain, die in BotFather registriert ist.
Was das in der Praxis bedeutet, laut Leadgrams Beitrag zur Änderung:
- Seiten auf der Domain der Mini App funktionieren weiter.
- Seiten auf einer anderen Domain, z.B. eine Angebotsseite, eine Zahlungsseite oder eine Auth-Seite, die innerhalb der Mini App geöffnet werden, können keine Mini App-Methoden mehr aufrufen. AdsGram verweist darauf, dass iframe-basierte und Multi-Domain-Setups betroffen sind.
- Alles andere funktioniert weiterhin. Drittanbieter-Seiten laden im WebView, und normale Links, HTTP-Weiterleitungen,
t.me-Links und serverseitige Aufrufe bleiben unberührt. Genau eine Sache wird blockiert: Aufrufen der Mini App-Methoden von einer fremden Domain. Einfachefetch-Aufrufe von Ihrer Seite zu einer separaten API-Domain betreffen eine andere Frage. - Die registrierte Domain muss die echte sein. Leadgram warnt, dass, wenn Ihre Mini App-URL auf eine Weiterleitung, einen Tracker oder einen URL-Shortener verweist, die Mini App auf dieser Domain registriert wird. Die echten Telegram-Aufrufe Ihrer Domain werden dann blockiert. Registrieren Sie die Endadresse.
Was es für localhost und Tunnel bedeutet
Die Regel bezieht sich auf Hostnamen. Diese Folgen ergeben sich daraus:
- Zufällige, rotierende URLs bedeuten, dass der Hostname, der Ihre Seite bedient, sich ändert, während der registrierte Hostname alt bleibt. Erwarten Sie, dass Mini App-Methoden scheitern, bis Sie sie überall aktualisieren.
- Eine stabile Subdomain ermöglicht es, den Ursprung der Mini App einmal zu registrieren. Die URL in BotFather, die von Ihrem Frontend verwendete und die in Ihrem Webhook verwendete bleiben über Neustarts hinweg gleich.
- Getrennte Umgebungen verdienen separate Hostnames, idealerweise mit einem separaten Dev-Bot.
Ein Debugging-Checkliste, wenn eine Mini App-Methode in der Entwicklung plötzlich stoppt:
- Vergleichen Sie den Ursprung der Seite mit der registrierten URL. Sind sie identisch, einschließlich Subdomain?
- Prüfen Sie auf eine Zwischen-Weiterleitung zwischen der registrierten URL und der Seite.
- Suchen Sie in Ihrem Code nach
Telegram.WebAppund prüfen Sie, welche Domains diese Seiten bedienen. Leadgram empfiehlt, den Pfad des Nutzers in Telegram Desktop oder web.telegram.org mit DevTools offen nachzugehen. - Suchen Sie nach iframes oder Navigationen zu anderen Domains, z.B. Auth-Anbietern oder Zahlungsseiten.
- Bestätigen Sie, dass der Tunnel-Hostname sich seit der letzten Registrierung nicht geändert hat.
Wenn eine fremde Seite nur close() oder openLink() aufruft, schlägt Leadgrams empfohlene Lösung vor, den Aufruf durch einen normalen https://t.me/...-Link oder eine Weiterleitung zu ersetzen.
Sollten Sie sich abmelden?
Der BotFather Mini App erlaubt Ihnen, den Schutz zu deaktivieren, aber Telegrams Formulierung ist eine Warnung: Durch das Abmelden übernehmen Sie die Verantwortung dafür, dass die Mini App keine Links zu untrusted Seiten hat. Das Abmelden stellt das alte Verhalten wieder her, bei dem jede Seite im WebView die App steuern kann, was genau das Loch war, das Telegram geschlossen hat. Ein Abmelden, um eine Entwicklungsumgebung zu ermöglichen, ist der falsche Weg, wenn das eigentliche Problem eine Origin-Mismatch ist. Beheben Sie den Mismatch, behalten Sie den Schutz bei und reservieren Sie Opt-out für Fälle, in denen Sie jede Seite, zu der die Mini App navigieren kann, vollständig kontrollieren.
Die Wahl eines Tunnels: Warum eine stabile Subdomain die praktische Lösung ist
Jedes Telegram-Konfigurationssegment in diesem Artikel bezieht sich auf eine URL: den Webhook-Endpunkt, die Mini App-Domain und den Ursprung, gegen den Telegram vergleicht, wenn eine Seite eine Mini App-Methode aufruft. Wenn sich die URL bei jedem Neustart ändert, registrieren Sie alle drei jedes Mal neu. Eine vergessene Aktualisierung führt zu verwirrenden Symptomen, wie z.B. stille Webhooks oder Mini App-Methoden, die gestern funktioniert haben, heute aber fehlschlagen.
Was die dokumentierten kostenlosen Optionen Ihnen bieten:
| Option | Hostname | Notes |
|---|---|---|
| ngrok Free | Eine zugewiesene Dev-Domain pro Konto, die sich beim Neustart des Agents nicht ändert | Limits gemäß ngrok-Dokumentation: 1 GB Datenübertragung nach außen und 20.000 HTTP-Anfragen pro Monat, bis zu 3 Online-Endpoints. Kostenlose Endpoints haben kein Timeout. |
| Cloudflare Quick Tunnel | Zufälliger trycloudflare.com-Hostname bei jedem Lauf |
Kein Konto nötig, aber Cloudflare kennzeichnet es als Test-Modus, mit 200 gleichzeitigen Anfragen und ohne Server-Sent Events. |
| Cloudflare named tunnel | Ein eigener Hostname, den Sie auf eigener Domain wählen | Benötigt Cloudflare-Konto und eine Domain. |
Beachten Sie die ngrok-Interstitial. In der Free-Tier zeigt ngrok eine Interstitial-Seite vor allen HTML-Browser-Traffic. ngrok sagt, dass dies keinen API- oder programmatic Zugriff beeinträchtigt, also sollten Webhook-Zustellungen unbeeinflusst bleiben. Eine Mini-App-Seite, die in Telegrams WebView geladen wird, ist HTML-Browser-Traffic, daher sehen Benutzer die Warnseite. ngrok dokumentiert zwei Wege, sie zu entfernen: Aufstieg zu jedem bezahlten Plan oder der Client sendet einen Skip-Header oder einen non-standard User-Agent. Der Header-Weg ist umständlich für eine Seite, die Telegrams WebView lädt.
Andere Tunneling-Dienste bieten stabile Subdomains in kostenlosen oder bezahlten Tarifen. Prüfen Sie die aktuellen Bedingungen Ihres Anbieters bezüglich Subdomain-Persistenz, Sitzungsdauer und Browser-Warnseiten, bevor Sie darauf angewiesen sind.
Eine Setup-Checkliste
- Erstellen Sie einen dedizierten Entwicklungs-Bot in BotFather.
- Wählen Sie einen Tunnel mit stabiler Hostname und verwenden Sie diese Hostname sowohl für den webhook als auch für die Mini App.
- Rufen Sie
setWebhookeinmal auf, mit einemsecret_tokenund einem engenallowed_updates. - Registrieren Sie die Mini App-URL auf derselben Hostname. Vermeiden Sie Weiterleitungen.
- Erlauben Sie den Hostname in Ihrem Dev-Server-Host-Check.
- Überprüfen Sie den Secret-Token-Header und das
initDataserverseitig. - Ignorieren und protokollieren Sie unbekannte Update-Felder, und deduplizieren Sie nach
update_id. - Wenn Deliveries stoppen, prüfen Sie zuerst
getWebhookInfo.
Häufig gestellte Fragen
Welche Ports kann Telegram Webhooks senden?
443, 80, 88 und 8443. Ein Tunnel öffnet Port 443 und leitet zu dem lokalen Port weiter, den Sie verwenden.
Was passiert, wenn mein Webhook einen Fehler zurückgibt?
Telegram behandelt Nicht-2xx-Antworten als Fehler und versucht erneut, bis zu einer „vernünftigen Anzahl von Versuchen“. Ein Endpunkt, der bei unerwarteter Eingabe Fehler wirft, kann wiederholte Deliveries verursachen.
Kann ich den Tunnel überspringen und getUpdates verwenden?
Für Bot-Logik ja, solange kein Webhook gesetzt ist. Eine Mini-App benötigt jedoch eine URL, die der Telegram-Client laden kann, daher benötigt es einen öffentlichen HTTPS-Hostnamen. Die Ausnahmen sind die Testumgebung und ein lokaler Bot API-Server, der nur die Bot-Seite abdeckt.
Ist der Secret-Token obligatorisch?
Nein, aber ohne ihn identifiziert nichts in einer Anfrage Telegram, und jeder, der Ihre Tunnel-URL findet, kann gefälschte Updates senden.
Ist Bot API 10.2 die neueste Version?
Nein. Bot API 10.3 (24. August 2026) und 10.4 (9. November 2026) wurden seitdem veröffentlicht. Das Webhook- und Mini-App-Origin-Verhalten hier gilt weiterhin.
Quellen
- Telegram Bot API-Changelog
- Telegram Bot API Referenz: setWebhook, getWebhookInfo, Update, lokaler Bot API-Server
- Telegram Mini Apps-Dokumentation: initData-Validierung, Testing, Debugging
- BotNews-Kanal auf Telegram (10.2-Origin-Warnung, 10.3 und 10.4-Ankündigungen)
- Telegram Bot API 10.2 Migrationsleitfaden, DEV Community
- Guide to Telegram webhooks, Hookdeck
- Mini App-Origin-Lockdown, Leadgram-Dokumentation
- Telegram Mini App-Entwicklungsfehler, AdsGram
- go-telegram/bot Bot API 10.4-Unterstützung (Widget-Update-Typen)
- ngrok Free Plan Limits
- Cloudflare Quick Tunnels
- Cloudflare Tunnel Getting Started (Quick Tunnel Limits)
- Öffnen Sie Ihren Dev-Server für die Öffentlichkeit, Quasar
- Beheben von „Blocked request“ in Strapi 5 (HMR clientPort)
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.