Quick Start
This page installs aiogram-webhook and shows the shortest useful setup for a single bot.
Install
aiogram-webhook requires Python 3.10 or newer and aiogram 3.14 or newer.
pip install aiogram-webhook
pip install "aiogram-webhook[fastapi]"
pip install "aiogram-webhook[aiohttp]"
uv add aiogram-webhook
uv add "aiogram-webhook[fastapi]"
uv add "aiogram-webhook[aiohttp]"
Optional extras
| Extra | Installs | Use it when |
|---|---|---|
fastapi |
FastAPI integration dependencies | Your webhook endpoint is served by a FastAPI application. |
aiohttp |
aiohttp integration dependencies | Your webhook endpoint is served by an aiohttp application. |
| none | Core aiogram webhook logic | You write your own WebAdapter or only use shared route/security helpers. |
Note
FastAPIAdapter is exported from aiogram_webhook only when FastAPI is installed.
AiohttpAdapter is always importable because aiohttp is already used by aiogram's default HTTP session.
Minimal app
Configure request verification
The engines work without security=..., but the library emits a warning because webhook endpoints are public HTTP routes.
Use a Telegram secret token, an IP check, or both for production deployments.
from contextlib import asynccontextmanager
from aiogram import Bot, Dispatcher, Router
from aiogram.filters import CommandStart
from aiogram.types import Message
from fastapi import FastAPI
from aiogram_webhook import FastAPIAdapter, SingleBotEngine, WebhookConfig
from aiogram_webhook.route import Route
from aiogram_webhook.security import IPCheck, Security, StaticSecretToken
router = Router()
@router.message(CommandStart())
async def start(message: Message) -> None:
await message.answer("OK")
dispatcher = Dispatcher()
dispatcher.include_router(router)
bot = Bot("BOT_TOKEN")
engine = SingleBotEngine(
dispatcher,
bot,
web=FastAPIAdapter(),
route=Route(base_url="https://example.com", path="/telegram/webhook"),
security=Security(IPCheck(), secret_token=StaticSecretToken("webhook-secret")),
webhook_config=WebhookConfig(drop_pending_updates=True),
)
@asynccontextmanager
async def lifespan(app: FastAPI):
await engine.set_webhook()
yield
app = FastAPI(lifespan=lifespan)
engine.register(app)
from aiohttp import web
from aiogram import Bot, Dispatcher, Router
from aiogram.filters import CommandStart
from aiogram.types import Message
from aiogram_webhook import AiohttpAdapter, SingleBotEngine, WebhookConfig
from aiogram_webhook.route import Route
from aiogram_webhook.security import IPCheck, Security, StaticSecretToken
router = Router()
@router.message(CommandStart())
async def start(message: Message) -> None:
await message.answer("OK")
dispatcher = Dispatcher()
dispatcher.include_router(router)
bot = Bot("BOT_TOKEN")
engine = SingleBotEngine(
dispatcher,
bot,
web=AiohttpAdapter(),
route=Route(base_url="https://example.com", path="/telegram/webhook"),
security=Security(IPCheck(), secret_token=StaticSecretToken("webhook-secret")),
webhook_config=WebhookConfig(drop_pending_updates=True),
)
async def set_webhook(app: web.Application) -> None:
await engine.set_webhook()
app = web.Application()
app.on_startup.append(set_webhook)
engine.register(app)
What the engine does
- Registers a
POSTendpoint in the selected web framework. - Matches path and query parameters with
Route. - Resolves the bot target.
- Runs security checks when configured.
- Parses Telegram's update JSON.
- Feeds the update into the aiogram
Dispatcher. - Returns either an empty
200JSON response or a Telegram method payload.
When should I call set_webhook?
Call set_webhook() from your application startup code after the public URL is reachable.
For SingleBotEngine, this method is available directly on the engine.
For TokenEngine, call add_bot(token) for every bot you want to register; it creates or reuses a Bot, builds its URL, and calls Telegram's setWebhook.