Integrate Telegram with VBWD: Event Notifications and a Telegram-Facing Bot

Two ways to connect Telegram to VBWD: push signed webhook events to a channel, and put a Telegram bot in front of VBWD’s grounded LLM assistant.

Telegram is where a lot of teams and customers already are; VBWD reaches it two ways — outbound signed webhooks for notifications, and a Telegram front-end for its AI bot.

Why Telegram is a good fit for VBWD

If you run a subscription business on VBWD, a lot of what happens is invisible until you go look for it: a trial converts, a payment fails, a subscription cancels. Telegram is where many small teams already live, so pushing those events into a channel you already check beats another dashboard nobody opens.

There are two clean ways to wire Telegram to VBWD, and they solve different problems. The first pushes events out of VBWD into a Telegram channel. The second puts a Telegram bot in front of VBWD so users can ask questions and get answers grounded in your own content. You can run either on its own, or both.

Neither requires touching VBWD core. VBWD is a self-hosted, source-available platform (Python/Flask, PostgreSQL, Redis, Vue 3, Docker) with an agnostic core: you extend it through seams like the event bus and outbound webhooks rather than forking it. That matters for upgrades, and it matters when you want a Telegram integration that survives the next version bump.

Pattern 1: notifications out via outbound webhooks

VBWD ships outbound webhooks. Every subscription lifecycle event can fire a signed HTTP POST to a URL you choose, and the subscriptions are managed through admin CRUD, so you register endpoints in the UI rather than in code. Each request carries an HMAC signature so the receiver can prove the payload really came from your VBWD instance.

The shape of the flow is small: VBWD fires a webhook, a tiny receiver you host verifies the HMAC, and then it calls Telegram’s Bot API to post a message. That receiver is the only new code you write, and it is generic — it does not need to know anything about VBWD internals beyond the shared secret.

Step by step

Create a bot in Telegram: message @BotFather, run /newbot, and copy the bot token it gives you.
Create a channel (or use an existing one), add your bot as an administrator, and get its chat_id. For a public channel you can use @yourchannel directly.
Stand up a small receiver service reachable over HTTPS. It verifies the HMAC signature, then calls sendMessage.
In the VBWD admin, register the receiver URL as a webhook target and select which subscription events should fire it.
Trigger a test event (a test subscription or a manual fire from admin) and confirm the message lands in your channel.

A minimal receiver looks like this:

import hmac, hashlib, os, requests
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["VBWD_WEBHOOK_SECRET"].encode()
BOT = os.environ["TELEGRAM_BOT_TOKEN"]
CHAT_ID = os.environ["TELEGRAM_CHAT_ID"]

@app.post("/hooks/vbwd")
def receive():
    body = request.get_data()
    sent = request.headers.get("X-VBWD-Signature", "")
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sent, expected):
        abort(401)  # reject anything we cannot verify

    event = request.get_json()
    text = f"[VBWD] {event['type']} for {event['data'].get('user_email','?')}"
    requests.post(
        f"https://api.telegram.org/bot{BOT}/sendMessage",
        json={"chat_id": CHAT_ID, "text": text},
        timeout=5,
    )
    return "", 204

A payload arriving at that endpoint is plain JSON, roughly:

{
  "type": "subscription.payment_failed",
  "id": "evt_9f2c...",
  "created_at": "2026-07-13T09:41:00Z",
  "data": {
    "subscription_id": "sub_1421",
    "user_email": "jane@example.com",
    "plan": "pro-monthly",
    "amount_due": "19.00"
  }
}

Note the compare_digest check. Verify the HMAC before you trust anything in the body — that single line is what stops a stranger who finds your receiver URL from spamming your channel with fake “payment failed” alerts. Read your event names and the exact signature header off the VBWD docs so you match them precisely; the names above are illustrative.

No-code variant

If you would rather not host a receiver, drop an automation tool between VBWD and Telegram. n8n or Zapier can accept the webhook, check the signature, and call sendMessage with a couple of nodes. You still keep the HMAC step — resist the temptation to accept unsigned requests just because the tool makes it easy. The tradeoff is another moving part and, on hosted plans, per-run cost, but it gets you a working alert pipeline in an afternoon.

Pattern 2: a Telegram bot in front of VBWD’s chat

The second pattern is the opposite direction. Instead of pushing events out, you let people talk to VBWD through Telegram. VBWD’s LLM chat bot rides the platform’s search-provider registry, so its answers are grounded on your own content, and it uses the LLM connection manager to reach whichever model you have configured. A Telegram bot becomes the front door.

The mechanics mirror Pattern 1 but reversed. Telegram sends every user message to a webhook you register with setWebhook. Your relay forwards the message text to the VBWD chat bot, gets a reply, and posts it back with sendMessage. This is a genuine two-way channel: support questions, “what plan am I on”, “how do I export my data”, answered from your content rather than a generic model.

Step by step

Enable the chat/LLM bot capability in your VBWD instance and configure an LLM connection. The plugins catalogue is where these capabilities are turned on.
Point Telegram at your relay: curl "https://api.telegram.org/bot<token>/setWebhook?url=https://you.example.com/tg".
In the relay, take the incoming message.text and message.chat.id, call the VBWD chat endpoint, and return the answer via sendMessage to that same chat_id.
Optionally map each Telegram user to a VBWD account so answers respect that user’s entitlements.

Usage here is metered by VBWD’s token system, the same accounting that governs the chat bot elsewhere. That is useful for business reasons: a Telegram front-end can get busy fast, and you want the cost of LLM calls attributed and capped rather than open-ended. Set limits before you publish the bot, not after the first surprising month.

Security notes worth repeating

Verify the HMAC on every inbound webhook. An unverified receiver is a public endpoint anyone can POST to. Reject on mismatch, and use a constant-time comparison, not ==.
Keep secrets in the environment. The bot token, the webhook secret, and any API keys belong in env vars or a secrets manager, never in the repo or a channel message.
Terminate TLS. Telegram will only call an HTTPS webhook, and you should hold your VBWD receiver to the same standard.
Commit your own writes. If your integration lives as a VBWD plugin and does DB work inside an event-bus callback, committing that write is the plugin’s responsibility — the callback will not do it for you, and a silent rollback is a nasty bug to chase.
Scope the bot’s admin rights. In Telegram, give the bot only the channel permissions it needs to post.

Honest limits

Telegram is a notification and conversation surface, not a system of record. Do not treat a channel message as proof an event happened — the webhook and your VBWD database are the source of truth, and Telegram delivery can lag or fail. If sendMessage errors, log it and move on; do not block the webhook response on Telegram being up, or you risk VBWD retrying the whole event.

Rate limits are real. Telegram will throttle a bot that posts too fast, so a burst of events (a billing run, a mass cancellation) can get you temporarily limited. Batch or debounce noisy event types rather than firing one message per row. And the LLM front-end is only as good as the content behind the search registry — a thin knowledge base produces thin answers, no matter which model you connect.

Finally, this is self-hosted. You own the receiver, the uptime, and the secrets. That is the point of running VBWD under BSL 1.1 rather than a closed SaaS, but it does mean the operational work is yours.

Takeaway

Two patterns, one platform. Outbound webhooks plus a fifteen-line receiver give you signed event alerts in a Telegram channel your team already reads. A Telegram bot in front of the VBWD chat bot gives your users a grounded, metered assistant where they already are. Both hang off documented seams, so neither forces you to edit core or fear the next upgrade. Start with notifications — it is the smaller build and the faster payoff — then add the conversational front-end once the alerts are earning their keep.