Webhooks

Webhooks let Telegram push updates to an ASP.NET Core endpoint.

Framework Webhooks

Install:

dotnet add package IWF.TeleFlow.Framework.Webhooks --prerelease
dotnet add package IWF.TeleFlow.Generators --prerelease

Register services:

builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddWebhook(options =>
{
    options.Path = "/telegram/webhook";
    options.SecretToken = webhookSecret;
});

Map endpoint:

var app = builder.Build();

app.MapTelegramWebhook();

await app.RunAsync();

MapTelegramWebhook() uses the configured TelegramWebhookOptions.Path and forwards incoming Telegram updates to the TeleFlow update processor.

The endpoint returns 200 OK only after the update processor completes normally. The full handling and failure contract is documented in update failure and delivery contract.

When To Use Webhooks

Use webhooks when:

• the bot already runs inside ASP.NET Core;
• a public HTTPS endpoint is available;
• your platform prefers HTTP-triggered workloads;
• you want Telegram to push updates instead of polling.

Secret Token

Use SecretToken when exposing webhook endpoints publicly:

builder.Services.AddWebhook(options =>
{
    options.Path = "/telegram/webhook";
    options.SecretToken = configuration["Telegram:WebhookSecret"];
});

The raw webhook layer validates the secret token and can reject invalid payloads.

Malformed JSON and payloads without a valid update_id are rejected as invalid requests. If a syntactically valid Telegram update cannot be decoded by the installed schema, ITelegramUpdateDecodeFailurePolicy decides delivery: Stop returns 500, while Skip returns 200 only after the policy completes. The default is Stop; use Skip only after durable quarantine.

Deployment Checklist

• Configure Telegram webhook URL outside the request handler.
• Use HTTPS.
• Keep the webhook path stable.
• Set and validate secret token.
• Route logs from ASP.NET Core and TeleFlow to the same observability platform.
• Keep request time short. Move long-running work behind your own queue if needed.