Telegram-Bot-Webhook auf localhost testen

Um einen Telegram-Bot-Webhook auf localhost zu testen, stellen Sie Ihren lokalen Server mit einem öffentlichen HTTPS-Tunnel bereit, rufen Sie setWebhook mit dieser URL auf und validieren Sie den Secret-Token-Header von Telegram bei jeder Anfrage. Dadurch erhalten Sie echte Nachrichten, Rückrufabfragen und Mitgliedschaftsaktualisierungen ohne Bereitstellung nach jeder Codeänderung. Die vollständige Schleife lautet: Führen Sie den Bot-Handler aus, starten Sie npx portpreview 3000, registrieren Sie die resultierende URL, senden Sie Ihrem Bot eine Nachricht und prüfen Sie die Anfrage lokal.

Warum Telegram Updates nicht direkt an localhost senden kann

Die Bot-API von Telegram sendet Webhook-Updates von der Telegram-Infrastruktur an eine über das Internet erreichbare URL. localhost, 127.0.0.1 und private LAN-Adressen können von dieser Infrastruktur aus nicht weitergeleitet werden. Ein localhost-Tunnel beendet HTTPS an einer öffentlichen Adresse und leitet die unveränderte HTTP-Anfrage an Ihren lokalen Port weiter.

Telegram-Bots können Updates auf zwei sich gegenseitig ausschließenden Wegen erhalten: langes Polling über getUpdates oder Webhooks. In der offiziellen setWebhook-Referenz heißt es, dass getUpdates nicht verfügbar ist, während ein ausgehender Webhook konfiguriert ist. Wenn ein Abfragevorgang noch läuft, stoppen Sie ihn, bevor Sie den Webhook-Fluss beurteilen.

Erstellen Sie einen lokalen Webhook-Endpunkt

Dieses Express-Beispiel hält den Handler absichtlich klein. Es überprüft das gemeinsame Geheimnis, bevor es das Update berührt, bestätigt es schnell und verschiebt die Arbeit außerhalb des Antwortpfads.

import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

function sameSecret(received = '', expected = '') {
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/telegram', (req, res) => {
  const received = req.get('x-telegram-bot-api-secret-token') || '';
  if (!sameSecret(received, process.env.TELEGRAM_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const update = req.body;
  res.sendStatus(200);
  queueMicrotask(() => handleUpdate(update));
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

Telegram sendet ein JSON-serialisiertes Update. Im Gegensatz zu HMAC-basierten Anbietern signiert die Funktion secret_token von Telegram den Text nicht. Der von Ihnen gewählte Wert wird in X-Telegram-Bot-Api-Secret-Token eingefügt. Das Token beweist, dass der Absender den bei der Registrierung des Webhooks verwendeten Wert kennt, stellt jedoch keinen Payload-Digest bereit. TLS schützt die Anfrage während der Übertragung.

Endpunkt mit HTTPS verfügbar machen

1. Starten Sie die App und bestätigen Sie, dass curl -i http://localhost:3000/webhooks/telegram den Server erreicht, auch wenn GET 404 zurückgibt.
2. Öffnen Sie ein zweites Terminal und führen Sie npx portpreview 3000 aus.
3. Kopieren Sie den öffentlichen HTTPS-Ursprung und hängen Sie /webhooks/telegram an.
4. Halten Sie den Tunnelprozess am Laufen, während Telegram Updates liefert.

Die Bot-API akzeptiert HTTPS-Webhook-URLs. Telegram dokumentiert Webhook-Unterstützung auf den Ports 443, 80, 88 und 8443; Der öffentliche Endpunkt eines verwalteten Tunnels verwendet normalerweise 443, auch wenn der weitergeleitete lokale Prozess auf 3000 lauscht.

Telegram-Webhook sicher registrieren

Erstellen Sie ein zufälliges Geheimnis, das nur Buchstaben, Ziffern, Unterstriche oder Bindestriche enthält. Telegramm erlaubt 1–256 Zeichen. Verwenden Sie das Bot-Token nicht als diesen Wert wieder.

export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -d "url=https://YOUR-TUNNEL.portpreview.dev/webhooks/telegram" \
  -d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" \
  -d 'allowed_updates=["message","callback_query"]' \
  -d "drop_pending_updates=true"

allowed_updates reduziert das Rauschen und sollte nur Update-Typen auflisten, die der Bot verarbeitet. drop_pending_updates=true ist nützlich, wenn Sie eine neue lokale Sitzung starten, aber Aktualisierungen in der Warteschlange werden dauerhaft verworfen. Lassen Sie es also weg, wenn diese Ereignisse von Bedeutung sind. Die Update-Dokumentation von Telegram beschreibt Felder wie message, callback_query und my_chat_member.

Bestätigen Sie die Registrierung, bevor Sie den Code debuggen

Verwenden Sie getWebhookInfo, um Konfigurationsfehler von Handlerfehlern zu trennen:

curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

Markieren Sie url, pending_update_count, last_error_message und last_error_date. Eine leere URL bedeutet, dass die Registrierung nicht aufrechterhalten wurde. Eine wachsende Anzahl ausstehender Dateien bedeutet normalerweise, dass Telegram keine Verbindung herstellen kann oder Ihr Endpunkt einen Nicht-2xx-Status zurückgibt. Senden Sie nach der Registrierung eine Direktnachricht an den Bot; Das bloße Öffnen des Chats führt nicht unbedingt zu einem Update.

Updates ohne Wiederholungsversuche verarbeiten

Vor langsamer Arbeit bestätigen

Eine 2xx-Antwort zurückgeben, sobald die Anfrage authentifiziert und dauerhaft akzeptiert wurde. Datenbankexporte, KI-Aufrufe und APIs von Drittanbietern sollten asynchron ausgeführt werden. Telegram wiederholt erfolglose Anfragen nach Nicht-2xx-Antworten, sodass langsame synchrone Arbeit zu Duplikaten führen kann.

Deduplizieren mit update_id

Jedes Update hat ein update_id. Speichern Sie verarbeitete IDs mit einem Ablauffenster oder erzwingen Sie einen eindeutigen Datenbankschlüssel. Bei einem erneuten Versuch darf kein zweiter Zahlungsbeleg gesendet, kein doppeltes Ticket erstellt oder derselbe Rückruf zweimal ausgeführt werden.

Jeden Aktualisierungstyp explizit modellieren

Nicht jedes Update enthält message.text. Rückrufschaltflächen kommen unter callback_query; Kanalbeiträge und Mitgliedschaftsänderungen haben andere Felder. Verzweigen Sie auf das aktuelle Feld der obersten Ebene und behandeln Sie unbekannte Typen als gültige No-Ops, statt sie auszulösen.

Sicherheitsregeln für lokale Telegram-Bot-Tests

• Validieren Sie zuerst den geheimen Header. Lehnen Sie fehlende oder falsche Werte ab, bevor Sie sensible Felder protokollieren oder analysieren.
• Halten Sie Token aus URLs und Protokollen fern. Das Bot-API-Token im Registrierungsbefehl ist ein Berechtigungsnachweis. Vermeiden Sie den Shell-Verlauf auf gemeinsam genutzten Systemen und rotieren Sie einen offengelegten Token über BotFather.
• Verwenden Sie eine unvorstellbare Route und ein Geheimnis. Die Route ist eine Tiefenverteidigung; Der geheime Header ist die eigentliche Anwendungsprüfung.
• Erfasste Daten beschränken. Nachrichten können Namen, Benutzernamen, Telefonnummern, Dateien und private Gesprächstexte enthalten. Protokolle schwärzen und lokale Aufnahmen löschen, wenn Sie fertig sind.
• Deaktivieren Sie niemals die Authentifizierung in der Entwicklung. Ein öffentlicher Tunnel ist öffentlich. Der lokale Code sollte die gleichen Prüfungen durchführen wie die Produktion.

Weitere Informationen zu Zugriffskontrolle und Datenaufbewahrungspraktiken finden Sie im umfassenderen Sicherheitsleitfaden für den lokalen Host-Tunnel.

Beheben Sie häufige Telegram-Webhook-Fehler

Telegram meldet einen Zertifikats- oder Verbindungsfehler

Verwenden Sie die HTTPS-URL des Tunnels, nicht sein lokales HTTP-Ziel. Bestätigen Sie, dass der Tunnel aktiv ist und sich die URL nicht geändert hat. Wenn Sie stattdessen Ihr eigenes selbstsigniertes Zertifikat bereitstellen, erfordert Telegram das Hochladen des öffentlichen Zertifikats als Datei; Ein verwalteter TLS-Endpunkt vermeidet dieses Setup.

Der Endpunkt gibt 401

zurück

Vergleichen Sie das an setWebhook übergebene Geheimnis mit der vom Prozess verwendeten Umgebungsvariablen. Bei Header-Namen wird die Groß-/Kleinschreibung nicht beachtet, aber Proxys oder Middleware können benutzerdefinierte Header entfernen. Untersuchen Sie die eingehenden Header, ohne den geheimen Wert auszugeben.

Keine Anfragen kommen

Führen Sie getWebhookInfo aus, überprüfen Sie, ob der registrierte Pfad genau mit Ihrer Route übereinstimmt, und stellen Sie sicher, dass keine Firewall die lokale Verbindung des Tunnels blockiert. Wenn Sie kürzlich Umfragen verwendet haben, vergewissern Sie sich, dass die Webhook-URL jetzt ausgefüllt ist. Lösen Sie ein tatsächliches Update aus, indem Sie dem Bot eine Nachricht senden.

Updates treffen wiederholt ein

Protokollstatus und Reaktionszeit. Ausnahmen nach Erhalt der Anfrage können dazu führen, dass aus einer beabsichtigten 200 eine 500 wird. Geben Sie 200 umgehend zurück, machen Sie die Verarbeitung idempotent und verwenden Sie die kontrollierte Webhook-Wiedergabe, anstatt beim Debuggen auf Wiederholungsversuche des Anbieters zu warten.

Testen Sie Rückrufabfragen und -dateien, nicht nur Text

Eine nützliche Bot-Testmatrix deckt mehr als message.text ab. Senden Sie ein Foto mit einer Bildunterschrift, teilen Sie einen Kontakt, bearbeiten Sie eine Nachricht und drücken Sie eine Taste auf der Inline-Tastatur. Rufen Sie bei Rückrufanfragen umgehend answerCallbackQuery auf, damit der Client seine Fortschrittsanzeige nicht mehr anzeigt, und führen Sie dann langsamere Arbeiten separat aus. Dateiaktualisierungen enthalten Kennungen; Das Herunterladen der Bytes ist ein zweiter Bot-API-Vorgang und sollte die Webhook-Antwort nicht verzögern.

Behalten Sie Fixtures bei, die aus bereinigten Updates für Unit-Tests erstellt wurden, aber behalten Sie den vollständigen Transportpfad für mindestens einen Test jedes unterstützten Typs bei. Eine Vorrichtung beweist, dass Ihr Dispatcher eine Nutzlast versteht; Eine echte getunnelte Zustellung beweist auch Registrierung, TLS, Header, Body-Parsing und Bestätigungsverhalten. Wenn Sie einen neuen allowed_updates-Eintrag hinzufügen, rufen Sie setWebhook erneut auf und überprüfen Sie, ob getWebhookInfo die beabsichtigte Konfiguration widerspiegelt.

Entfernen Sie den Webhook nach der lokalen Sitzung

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook" \
  -d "drop_pending_updates=false"

Durch das Löschen des Webhooks kehren Sie zu getUpdates zurück. Wenn sich die Tunnel-URL bei der nächsten Sitzung ändert, rufen Sie setWebhook erneut auf. Befolgen Sie für zusätzliche Diagnosen den allgemeinen lokalen Webhook-Debugging-Workflow.