Skip to content

Webhooks

Webhooks позволяют Telegram пушить updates в ASP.NET Core endpoint.

Framework webhooks

Установка:

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

Регистрация 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;
});

Endpoint mapping:

var app = builder.Build();

app.MapTelegramWebhook();

await app.RunAsync();

MapTelegramWebhook() использует configured TelegramWebhookOptions.Path и передаёт incoming Telegram updates в TeleFlow update processor.

Endpoint возвращает 200 OK только после нормального завершения update processor. Полный handling и failure contract описан в контракте ошибок и подтверждения update.

Когда использовать webhooks

Webhooks подходят, когда:

  • бот уже работает внутри ASP.NET Core;
  • доступен public HTTPS endpoint;
  • platform предпочитает HTTP-triggered workloads;
  • ты хочешь, чтобы Telegram pushed updates instead of polling.

Secret token

Используй SecretToken, когда webhook endpoint доступен публично:

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

Raw webhook layer валидирует secret token и может отклонять invalid payloads.

Невалидный JSON и payload без корректного update_id отклоняются как invalid requests. Если синтаксически валидный Telegram update не декодируется установленной schema, доставкой управляет ITelegramUpdateDecodeFailurePolicy: Stop возвращает 500, а Skip возвращает 200 только после успешного завершения policy. Default — Stop; используй Skip только после durable quarantine.

Deployment checklist

  • Настраивай Telegram webhook URL вне request handler.
  • Используй HTTPS.
  • Держи webhook path стабильным.
  • Установи и валидируй secret token.
  • Отправляй ASP.NET Core и TeleFlow logs в одну observability platform.
  • Держи request time коротким. Long-running work выноси за свою queue, если нужно.