First Webhook

Written by
Updated at June 10, 2026

Deployment checklist. This page explains why each step matters — copy-paste code is on the home page.

What changes from polling

Part Change
Handlers, routers, FSM None — move as-is
Process bootstrap Web framework + engine instead of start_polling()
Public URL Telegram must reach HTTPS
set_webhook() Registers that URL with Telegram
Security Verifies incoming requests at the public endpoint

Tip

Develop handlers with long polling locally; switch to webhooks for deployment. Only bootstrap code changes.

1. Handlers stay ordinary aiogram

from aiogram import Dispatcher, Router
        from aiogram.filters import CommandStart
        from aiogram.types import Message
        
        router = Router()
        
        
        @router.message(CommandStart())
        async def start(message: Message) -> None:
            await message.answer("Webhook is alive")
        
        
        dispatcher = Dispatcher()
        dispatcher.include_router(router)

2. Wire engine and adapter

The engine connects dispatcher, bot, adapter, route, and security in one place — copy the minimal app from the home page.

Two registrations

Step Call Purpose
Local route + lifecycle engine.register(app) Registers POST route and wires engine startup/shutdown in your web framework.
Telegram delivery await engine.set_webhook() Tells Telegram the public HTTPS URL for future updates.

Run set_webhook() from framework startup after the endpoint is reachable. For TokenEngine, call add_bot(token) per bot instead.

Adapter-specific details: FastAPI · aiohttp

3. Expose a public HTTPS URL

Telegram delivers updates only over HTTPS to an internet-reachable host.

Environment Typical approach
Local development Tunnel (ngrok, cloudflared) or staging server
Production Reverse proxy (nginx, Caddy) or platform load balancer

Route(base_url=...) must match the public origin — scheme, host, and port if non-standard.

Warning

Do not use http://localhost in base_url unless Telegram can reach it. For local work, put the tunnel's HTTPS URL in base_url.

Checklist before set_webhook()

4. Register with Telegram

Call after the endpoint is reachable:

await engine.set_webhook()  # SingleBotEngine
        await engine.add_bot("123456:ABCDEF")  # TokenEngine

The engine forwards WebhookConfig fields and the secret from Security, so Telegram registration and request verification stay aligned. Details: WebhookConfig.

How do I know Telegram accepted it?

set_webhook() returns True on success. Inspect live state:

info = await bot.get_webhook_info()
        print(info.url, info.last_error_message)

Empty url or a set last_error_message means fix connectivity or TLS before debugging handlers.

5. Verify end-to-end

  1. Send /start in Telegram.
  2. Confirm the handler reply arrives.
  3. On failure, check Errors and application logs (aiogram_webhook logger).

Request flow diagram: Dispatch modes.

Where to go next

Topic Page
Secret token and IP checks Security
allowed_updates, drop_pending_updates WebhookConfig
Project file layout Single-bot app
Several bots on one service Multi-bot app
Previous
Home
Next
Web adapters