Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme

Güncellendi: 29 Ekim 2026 · 7 dk okuma

Telegram bot webhook'u kurmak için setWebhook metoduna herkese açık bir HTTPS URL vermeniz yeterli: Telegram her yeni güncellemeyi bu adrese JSON olarak POST eder. Bu rehberde webhook URL'sini ayarlamayı, secret token ile istekleri doğrulamayı, getWebhookInfo ile hata ayıklamayı ve n8n gibi araçlarda sık görülen sorunları anlatıyoruz.

Webhook mi, getUpdates mi?

İki yöntem birbirini dışlar. Hangisini seçerseniz seçin, alınmayan güncellemeler en fazla 24 saat saklanır.

Webhook gereksinimleri

• İnternetten erişilebilen bir alan adı (kendinden imzalı sertifikada IP de olur). Webhook'lar IPv4 üzerinden çalışır; IPv6 desteklenmez.
• TLS 1.2 veya üstü ile HTTPS. Düz HTTP webhook mümkün değildir.
• Port: 443, 80, 88 veya 8443; başka port çalışmaz.
• Güvenilir bir sertifika (ör. Let's Encrypt). CN veya SAN alan adıyla birebir eşleşmeli, ara sertifikalar (zincir) eksiksiz sunulmalı. Kendinden imzalı sertifikayı certificate parametresiyle yükleyin.
• Yönlendirmeler (redirect) desteklenmez; URL doğrudan bot uygulamanıza ulaşmalı.

setWebhook ile Telegram bot webhook URL ayarlama

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bot.ornek.com/telegram/webhook",
    "secret_token": "uzun-ve-rastgele_bir-deger_42",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true,
    "max_connections": 40
  }'

Başarılı yanıt: {"ok":true,"result":true,"description":"Webhook was set"}. Parametreler:

• url — HTTPS adresi. Boş metin gönderirseniz webhook kaldırılır.
• secret_token — 1–256 karakter, yalnızca A-Z a-z 0-9 _ -. Her istekte X-Telegram-Bot-Api-Secret-Token başlığında gelir.
• allowed_updates — almak istediğiniz güncelleme türleri. Hiç göndermezseniz önceki ayar korunur.
• drop_pending_updates — true ise bekleyen güncellemeler silinir.
• max_connections — eşzamanlı bağlantı sayısı, 1–100 (varsayılan 40).
• certificate ve ip_address — kendinden imzalı sertifika ve DNS yerine kullanılacak sabit IP.

Kendinden imzalı sertifikayla kurulum dosya yüklemesi gerektirir:

curl -F "url=https://203.0.113.10:8443/webhook" \
     -F "certificate=@public.pem" \
     "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook"

Parametreleri form üzerinden denemek için Bot API Tester'da setWebhook metodunu açın.

getWebhookInfo ile durumu kontrol etme

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getWebhookInfo"

{
  "ok": true,
  "result": {
    "url": "https://bot.ornek.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 7,
    "last_error_date": 1793264400,
    "last_error_message": "Wrong response from the webhook: 500 Internal Server Error",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

pending_update_count sürekli artıyorsa Telegram güncellemeleri teslim edemiyordur; nedeni last_error_message alanında yazar (sertifika hatası, zaman aşımı, 2xx olmayan yanıt vb.). last_error_date Unix zamanıdır. url boşsa webhook kurulu değildir.

Webhook secret token'ı handler'da doğrulama

Başlığı kontrol etmeyen bir uç nokta, adresi bilen herkesten sahte güncelleme kabul eder. Python ve Flask ile örnek:

import hmac
import os
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]

@app.post("/telegram/webhook")
def telegram_webhook():
    received = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(received.encode(), SECRET.encode()):
        abort(403)
    update = request.get_json(silent=True) or {}
    queue_update(update)  # kendi kuyruk fonksiyonunuz; ağır işi arka planda yapın
    return "", 200

Hızlıca 2xx yanıt verin

Telegram, 2xx dışındaki her yanıtı başarısız sayar ve isteği bir süre tekrar dener. Handler'ınız yavaşsa veya hata veriyorsa güncellemeler birikir ve aynı güncelleme tekrar gelebilir. Bu yüzden önce 200 döndürün, işi kuyrukta yapın ve tekrarları update_id ile ayıklayın.

deleteWebhook ile polling'e dönme

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteWebhook?drop_pending_updates=true"

drop_pending_updates isteğe bağlıdır; bekleyen güncellemeleri korumak istiyorsanız eklemeyin. Webhook silindikten sonra getUpdates yeniden çalışır.

Sorun giderme

Bad Request: bad webhook: An HTTPS URL must be provided for webhook

url parametresine http:// ile başlayan bir adres verdiniz. Geçerli sertifikalı bir https:// adresi kullanın.

409 Conflict

Webhook kuruluyken getUpdates çağrılırsa şu yanıt gelir: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first. Ya webhook'u silin ya da polling yapan kodu durdurun. Aynı token'ı iki farklı araca vermek de bu çakışmanın sık bir nedenidir.

Telegram bot webhook ve n8n: localhost sorunu

n8n'in Telegram tetikleyicisi güncellemeleri webhook ile alır. n8n yalnızca bilgisayarınızda http://localhost üzerinde çalışıyorsa Telegram ona ulaşamaz ve HTTPS koşulu sağlanmaz. n8n'i geçerli sertifikalı bir alan adında yayınlayın ya da yerel geliştirme için bir HTTPS tüneli kullanın. Aynı bot için ayrıca getUpdates çalıştırmayın; n8n'e ayrı bir bot ayırmak en temizidir (bkz. bot token rehberi).

setWebhook başarılı ama güncelleme gelmiyor

getWebhookInfo çıktısındaki last_error_message alanına bakın; eksik sertifika zinciri, güvenlik duvarı, yönlendirme veya yalnızca IPv6 destekleyen sunucu en sık nedenlerdir. Botu ilk kez kuruyorsanız Telegram bot yapma rehberindeki getUpdates adımlarıyla başlamak daha kolaydır.