Integrations

Telegram Webhooks Guide

Telegram Bot API webhooks send bot updates to an HTTPS endpoint. A production bot needs a stable URL, secret token verification, route separation for update types, and useful evidence when a downstream handler fails.

FastHook supports Telegram as a provider source. Telegram sends updates to the FastHook source URL, FastHook checks x-telegram-bot-api-secret-token when configured, and accepted updates are routed to your destinations through connections.

Telegram delivery model

  1. Create a Telegram bot and generate a bot token.
  2. Create a FastHook Telegram source and copy the Source URL.
  3. Call setWebhook with the FastHook URL and a secret_token.
  4. Use the same secret token in FastHook source auth.
  5. Route accepted updates to your bot backend, queue, Slack alert, or Google Sheet.

Secret token header

HeaderPurpose
x-telegram-bot-api-secret-tokenStatic token Telegram includes when setWebhook secret_token is configured.
Content-TypeTelegram sends JSON update payloads.
Update bodyContains update_id and one update object such as message, callback_query, or inline_query.

Create a Telegram source

Create source
curl -X POST "https://api.fasthook.io/v1/sources" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_3b5335b627084a838b" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram bot updates",
    "type": "TELEGRAM",
    "config": {
      "auth_type": "PROVIDER_SIGNATURE",
      "auth": {
        "provider": "TELEGRAM",
        "webhook_signing_secret": "telegram-secret-token"
      },
      "allowed_http_methods": ["POST"]
    }
  }'

Configure Telegram

setWebhook
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -d "url=https://hook-xxxxxx.fasthook.io/" \
  -d "secret_token=telegram-secret-token"

Routing ideas

  • Route message updates to the bot application.
  • Route callback_query updates to workflow handlers.
  • Route errors or admin commands to a Gmail destination or an HTTP destination that points to Slack.
  • Send low-volume audit events to Google Sheets for support review.

Update type filters

Telegram update payloads can carry different objects under the same webhook URL. Keep routing explicit so a message handler does not accidentally receive callback queries, inline queries, or bot admin commands it does not understand.

Telegram message filter
{
  "type": "filter",
  "body": {
    "message": { "$exists": true }
  }
}

Debugging Telegram deliveries

If Telegram reports webhook failures, first check whether FastHook captured the request. If the request is rejected, compare the secret token header and source configuration. If the request is accepted but your bot did not respond, inspect the routed event and destination attempt response body.

  • Use one source per bot so secret-token rotation is isolated.
  • Keep the Bot API token out of FastHook payload examples and screenshots.
  • Route high-volume message updates away from human notification destinations.
  • Retry only after the bot receiver can handle duplicate update ids.

Related guides