Webhook runtime for aiogram

aiogram-webhook

A compact webhook layer for aiogram applications. Register FastAPI or aiohttp endpoints, build public Telegram URLs, verify requests, and run single-bot or token-based multi-bot webhooks.

Quick start First webhook

Main building blocks

The important parts are visible directly in the navigation.

Webs

Choose FastAPI, aiohttp, or a custom web adapter for your framework boundary.

Engines

Resolve the target bot, call aiogram dispatcher, and control background handling.

Route

Build Telegram webhook URLs and validate path and query parameters.

Security

Verify Telegram secret-token headers, IP ranges, and custom request checks before dispatch.

Configuration and behavior

Tune Telegram registration and understand how requests are handled.

Telegram options

Configure setWebhook fields such as allowed updates, pending updates, and max connections.

TokenEngine config

Configure bot creation defaults and per-bot webhook options for multi-bot apps.

Webhook behavior

Read about background handling, webhook replies, startup, and shutdown.

Operations

Debug public error responses and prepare production deployments.

Minimal FastAPI setup

from aiogram import Bot, Dispatcher
        from fastapi import FastAPI
        
        from aiogram_webhook import FastAPIAdapter, SingleBotEngine
        from aiogram_webhook.route import Route
        
        dispatcher = Dispatcher()
        bot = Bot("BOT_TOKEN")
        
        engine = SingleBotEngine(
            dispatcher,
            bot,
            web=FastAPIAdapter(),
            route=Route(base_url="https://example.com", path="/webhook"),
        )
        
        app = FastAPI()
        engine.register(app)

Call await engine.set_webhook() during application startup when your public HTTPS URL is ready.

Recipes

Use these after the individual parts are clear.

First webhook

Combine SingleBotEngine, Route, one adapter, and optional Security for a first endpoint.

Multi-bot app

Combine TokenEngine, BotTokenParam, BotConfig, and shared webhook defaults.

Errors

Map public HTTP responses to route, security, engine, and shutdown causes.