InstaTunnel
Navigationsmenu umschalten
Tutorial
15 min read
28 views

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.

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
Telegram-Bots und Mini-Apps auf Localhost: setWebhook, der Secret-Token-Header und die neue Origin-Check

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_user und ephemeral_message_id in Message.
  • Rich messages: InputRichMessage erhielt blocks und media-Felder.
  • Communities: ein neuer Typ Community, community_chat_added und community_chat_removed Service-Nachrichten, und ein community-Feld in ChatFullInfo.
  • Subscriptions: ein neues Top-Level-Feld subscription in Update, das ein BotSubscriptionUpdated-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_parameters zusammengeführt
    • Ein nativer Stop-Button für gestreamte Entwürfe
    • Ein neues stopped_message_generation-Feld in Update
  • Bot API 10.4 (9. November 2026):
    • HTML-Widgets über sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData und editSharedWidgetData
    • TON-Wallet-Karten und Transferdienstnachrichten
    • Ephemere Antworten, ausgelöst durch Button-Drücke
    • Laut Release Notes der Bibliothek neue Typen widget_query und shared_widget_query

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 getUpdates empfangen.
  • 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 getWebhookInfo auf, wann immer Deliveries anhalten. Es meldet die aktuelle URL, pending_update_count, last_error_date, last_error_message und die aktiven allowed_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 vermeide DisallowUnknownFields im Decoder. In Rust mit serde füge nicht deny_unknown_fields zu 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:

  1. Starten Sie Ihren Frontend-Dev-Server auf einem lokalen Port.
  2. Starten Sie den Tunnel und notieren Sie den öffentlichen HTTPS-Hostnamen.
  3. Setzen Sie diese URL dort, wo Ihre Mini-App gestartet wird. Telegram dokumentiert mehrere Routen: ein web_app Inline- oder Tastatur-Button, der Bot-Menü-Button (BotFather’s /setmenubutton oder Bot Settings → Menu Button), die Haupt-Mini-App in BotFather und direkte Links in der Form https://t.me/botusername/appname.
  4. Ö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 .localhost oder einer IP-Adresse. Andernfalls kommt „Blocked request. This host is not allowed.“ Fügen Sie Ihren Tunnel-Hostnamen zu server.allowedHosts hinzu. Ein führender Punkt (.) entspricht Subdomains. Setzen Sie nicht allowedHosts: 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.clientPort auf 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:

  1. Entfernen Sie das Feld hash. Lassen Sie jedes andere empfangene Feld, einschließlich signature, das für Drittanbieter-Verifikation existiert.
  2. Sortieren Sie die restlichen key=value-Paarungen nach Schlüssel und verbinden Sie sie mit Zeilenumbrüchen (\n).
  3. Berechnen Sie einen Secret-Key: HMAC-SHA256 des Bot-Tokens, wobei der konstante String WebAppData als Schlüssel verwendet wird.
  4. Berechnen Sie den HMAC-SHA256 des Data-Check-Strings mit diesem Secret-Key, als Hex.
  5. Vergleichen Sie es mit hash in konstanter Zeit und lehnen Sie ab, wenn auth_date veraltet 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. Einfache fetch-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:

  1. Vergleichen Sie den Ursprung der Seite mit der registrierten URL. Sind sie identisch, einschließlich Subdomain?
  2. Prüfen Sie auf eine Zwischen-Weiterleitung zwischen der registrierten URL und der Seite.
  3. Suchen Sie in Ihrem Code nach Telegram.WebApp und 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.
  4. Suchen Sie nach iframes oder Navigationen zu anderen Domains, z.B. Auth-Anbietern oder Zahlungsseiten.
  5. 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

  1. Erstellen Sie einen dedizierten Entwicklungs-Bot in BotFather.
  2. 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.
  3. Rufen Sie setWebhook einmal auf, mit einem secret_token und einem engen allowed_updates.
  4. Registrieren Sie die Mini App-URL auf derselben Hostname. Vermeiden Sie Weiterleitungen.
  5. Erlauben Sie den Hostname in Ihrem Dev-Server-Host-Check.
  6. Überprüfen Sie den Secret-Token-Header und das initData serverseitig.
  7. Ignorieren und protokollieren Sie unbekannte Update-Felder, und deduplizieren Sie nach update_id.
  8. 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

Continue from this article into the most relevant product guides and workflows.

Related Topics

#telegram bot localhost#telegram mini app localhost#telegram setWebhook#telegram webhook localhost#telegram bot api 10.2#telegram bot api update#telegram secret token header#X-Telegram-Bot-Api-Secret-Token#telegram webhook secret token#telegram mini app origin check#telegram mini app origin protection#telegram mini app development#telegram web app development#telegram mini apps tutorial#telegram bot tutorial#telegram bot webhook tutorial#telegram bot webhook https#telegram bot webhook tunnel#telegram bot ngrok alternative#telegram bot local development#test telegram bot locally#telegram bot webhook testing#telegram bot setWebhook error#telegram webhook not working#telegram webhook 404#telegram webhook ssl error#telegram bot retry updates#telegram bot unknown fields#telegram bot api migration guide#telegram bot api breaking changes#telegram botfather settings#telegram botfather mini app#botfather origin protection opt out#telegram mini app domain#telegram mini app stable subdomain#telegram mini app https localhost#telegram webhook vs long polling#telegram getUpdates vs webhook#telegram bot webhook security#telegram webhook validation#telegram initData validation#telegram web app initData#localhost tunneling#localhost tunnel for webhooks#expose localhost to internet#localhost https tunnel#static subdomain tunnel#persistent tunnel url#webhook testing tools#webhook debugging#local webhook development#developer infrastructure#cloud native development#devops tools#secure tunneling#reverse proxy for webhooks#instatunnel#telegram bot node.js webhook#telegram bot python webhook#telegram bot 2026

Keep building with InstaTunnel

Read the docs for implementation details or compare plans before you ship.

Share this article

More InstaTunnel Insights

Discover more tutorials, tips, and updates to help you build better with localhost tunneling.

Browse All Articles