Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error

Diperbarui: 29 Oktober 2026 · 8 menit baca

Webhook telegram bot membuat Telegram mengirim setiap update ke URL HTTPS milikmu lewat request POST, jadi bot tidak perlu terus-menerus memanggil getUpdates. Caranya: panggil setWebhook sekali dengan URL publik, tambahkan secret_token untuk keamanan, lalu cek statusnya dengan getWebhookInfo.

Webhook vs getUpdates

Kedua cara ini tidak bisa dipakai bersamaan. Apa pun pilihannya, update disimpan di server Telegram maksimal 24 jam sampai diterima bot. Kalau baru mulai, polling sudah cukup. Lihat panduan cara membuat bot Telegram.

Syarat webhook

• URL HTTPS publik. Server Bot API resmi tidak menerima URL http://, dan alamat localhost tidak bisa dijangkau Telegram.
• Port: hanya 443, 80, 88, atau 8443. Port selain 443 ditulis di URL, misalnya https://bot.example.com:8443/webhook.
• Sertifikat: sertifikat valid dari CA tepercaya dengan rantai intermediate yang lengkap, atau sertifikat self-signed yang diunggah lewat parameter certificate. CN/SAN harus cocok dengan domain, dan minimal TLS 1.2.
• IPv4 (IPv6 belum didukung untuk webhook), dan tanpa redirect.

Cara setting webhook dengan setWebhook

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

Jika berhasil, API mengembalikan "result": true. Arti parameternya:

• url: alamat HTTPS penerima update.
• secret_token: 1–256 karakter, hanya A-Z, a-z, 0-9, _, dan -. Dikirim di header X-Telegram-Bot-Api-Secret-Token pada setiap request.
• allowed_updates: jenis update yang ingin diterima. Kalau tidak diisi, pengaturan sebelumnya yang dipakai.
• drop_pending_updates: buang update yang menumpuk sebelum webhook dipasang.
• max_connections: koneksi simultan 1–100, default 40.
• certificate dan ip_address: untuk sertifikat self-signed dan IP tetap.

Sertifikat self-signed harus diunggah sebagai file (multipart), bukan string:

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

Ingin mencoba tanpa terminal? Buka setWebhook di Bot API Tester, isi parameter di form, lalu jalankan.

Cek status dengan getWebhookInfo

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

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

• url kosong berarti webhook tidak terpasang dan bot memakai getUpdates.
• pending_update_count yang terus bertambah berarti update tidak berhasil terkirim.
• last_error_message dan last_error_date menunjukkan error terakhir: respons non-2xx, timeout, atau masalah sertifikat.

Verifikasi header X-Telegram-Bot-Api-Secret-Token

URL webhook bisa ditebak atau bocor. Dengan secret_token, handler bisa menolak request yang tidak berasal dari webhook milikmu. Contoh dengan Flask:

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():
    got = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(got, SECRET):
        abort(403)
    update = request.get_json(silent=True) or {}
    handle_update(update)  # fungsi milikmu, usahakan cepat
    return "", 200

Jangan memakai token bot sebagai path URL. Path bisa tercatat di log server, sedangkan secret_token dikirim lewat header.

Balas 2xx secepatnya

Jika server membalas selain 2xx, Telegram mengulang pengiriman update beberapa kali sebelum menyerah. Akibatnya update menumpuk dan bisa diproses dua kali. Tips:

• Balas 200 segera, lalu kerjakan proses berat (AI, database, API lain) di background atau antrean.
• Simpan update_id yang sudah diproses untuk mengabaikan update duplikat.
• Jangan sampai error di logika bot membuat handler membalas 500 terus-menerus.

Untuk membalas pengguna, panggil sendMessage seperti di panduan kirim pesan bot Telegram.

Kembali ke polling dengan deleteWebhook

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

Parameter drop_pending_updates opsional. Tanpa parameter itu, update yang menunggu tetap bisa diambil dengan getUpdates.

Troubleshooting webhook telegram bot

• Error 400 berisi An HTTPS URL must be provided for webhook. URL diawali http://. Gunakan https:// dengan sertifikat yang valid.
• 409 Conflict saat memanggil getUpdates. Webhook masih aktif. Hapus dengan deleteWebhook, atau tetap pakai webhook dan hentikan skrip polling.
• Webhook tiba-tiba berhenti. Satu bot hanya punya satu webhook. Aplikasi lain dengan token yang sama mungkin memanggil setWebhook dan menimpa URL kamu. Cek url di getWebhookInfo, dan pakai bot terpisah per integrasi. Jika token bocor, baca panduan token bot Telegram.
• Webhook telegram n8n di localhost. Jika n8n berjalan di localhost atau hanya HTTP, Telegram tidak bisa mengirim update. n8n harus bisa diakses dari internet lewat HTTPS, misalnya di server dengan domain dan sertifikat, atau lewat tunnel HTTPS. Setelah itu pastikan getWebhookInfo menampilkan URL publik tersebut.
• Masalah sertifikat. Rantai intermediate tidak lengkap atau CN tidak cocok dengan domain. Detailnya ada di panduan webhook resmi.