{"id":51196410,"url":"https://github.com/dengaleev/superset-telegram-bridge","last_synced_at":"2026-06-27T21:02:57.143Z","repository":{"id":361924284,"uuid":"1256140460","full_name":"dengaleev/superset-telegram-bridge","owner":"dengaleev","description":"Forward Apache Superset alert \u0026 report notifications to a Telegram chat. Single Go binary, distroless container","archived":false,"fork":false,"pushed_at":"2026-06-01T21:24:48.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T22:07:30.463Z","etag":null,"topics":["alerting","apache-superset","docker","go","golang","monitoring","notifications","superset","telegram","telegram-bot","webhook"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dengaleev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T13:54:15.000Z","updated_at":"2026-06-01T21:24:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dengaleev/superset-telegram-bridge","commit_stats":null,"previous_names":["dengaleev/superset-telegram-bridge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dengaleev/superset-telegram-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dengaleev%2Fsuperset-telegram-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dengaleev%2Fsuperset-telegram-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dengaleev%2Fsuperset-telegram-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dengaleev%2Fsuperset-telegram-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dengaleev","download_url":"https://codeload.github.com/dengaleev/superset-telegram-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dengaleev%2Fsuperset-telegram-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34867617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alerting","apache-superset","docker","go","golang","monitoring","notifications","superset","telegram","telegram-bot","webhook"],"created_at":"2026-06-27T21:02:56.319Z","updated_at":"2026-06-27T21:02:57.138Z","avatar_url":"https://github.com/dengaleev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# superset-telegram-bridge\n\n[![CI](https://github.com/dengaleev/superset-telegram-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/dengaleev/superset-telegram-bridge/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dengaleev/superset-telegram-bridge)](https://goreportcard.com/report/github.com/dengaleev/superset-telegram-bridge)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/dengaleev/superset-telegram-bridge)](go.mod)\n[![Release](https://img.shields.io/github/v/release/dengaleev/superset-telegram-bridge?sort=semver)](https://github.com/dengaleev/superset-telegram-bridge/releases)\n[![License: MIT](https://img.shields.io/github/license/dengaleev/superset-telegram-bridge)](LICENSE)\n\nA single-binary service that forwards [Apache Superset](https://superset.apache.org/) alert and report notifications to a Telegram chat.\n\nSuperset can POST notifications to a webhook URL. This bridge receives that webhook, turns it into a Telegram message with an inline \"Open in Superset\" link, forwards any attachments as photos or documents, and sends it through the Telegram Bot API.\n\n```\n  Superset alert/report\n      │\n      │  POST /webhook   (JSON, or multipart/form-data with attachments)\n      ▼\n  superset-telegram-bridge\n      │\n      │  Telegram Bot API\n      │      text        → sendMessage   (HTML + \"Open in Superset\" link)\n      │      PNG         → sendPhoto\n      │      CSV, PDF    → sendDocument\n      ▼\n  Telegram chat\n```\n\n## Contents\n\n- [What it does](#what-it-does)\n- [Quick start](#quick-start)\n- [Configuration](#configuration)\n- [Endpoints](#endpoints)\n- [Superset setup](#superset-setup)\n- [Security](#security)\n- [Local playground](#local-playground)\n- [Development](#development)\n- [Releasing](#releasing)\n\n## What it does\n\n- Formats text notifications as HTML Telegram messages — bold title, italic description, an inline \"Open in Superset\" link, link previews off.\n- Forwards report attachments: `image/png` files go as photos, other files (CSV, PDF, …) as documents. Several files of one kind are grouped into an album, with the notification text as the caption.\n- Retries a failed send once after a short fixed delay; a non-2xx response is returned as-is. The bot token is stripped from transport errors before they're logged.\n- Logs JSON via `slog`, serves `GET /healthz`, shuts down gracefully, and caps the request body at 50 MiB.\n- Builds to a static, non-root distroless image (under 10 MB) for `linux/amd64` and `linux/arm64`, published to GHCR on each release.\n\n## Quick start\n\nWith `docker run`:\n\n```bash\ndocker run -d --name superset-bridge \\\n  -p 8080:8080 \\\n  -e TELEGRAM_TOKEN=\"123456:your-bot-token\" \\\n  -e TELEGRAM_CHAT_ID=\"-1001234567890\" \\\n  ghcr.io/dengaleev/superset-telegram-bridge:latest\n```\n\nOr with Docker Compose (`compose.yaml`):\n\n```yaml\nservices:\n  bridge:\n    image: ghcr.io/dengaleev/superset-telegram-bridge:latest\n    ports:\n      - \"8080:8080\"\n    environment:\n      TELEGRAM_TOKEN: \"123456:your-bot-token\"\n      TELEGRAM_CHAT_ID: \"-1001234567890\"\n    restart: unless-stopped\n```\n\n```bash\ndocker compose up -d\n```\n\nThen point a Superset notification at `http://\u003chost\u003e:8080/webhook` (see [Superset setup](#superset-setup)).\n\n\u003e Need a bot token and chat ID? Create a bot with [@BotFather](https://t.me/BotFather), add it to your target chat, and read the chat ID from `https://api.telegram.org/bot\u003cTOKEN\u003e/getUpdates`.\n\n## Configuration\n\nAll configuration is via environment variables.\n\n| Variable           | Required | Default | Description                                                                  |\n| ------------------ | :------: | ------- | ---------------------------------------------------------------------------- |\n| `TELEGRAM_TOKEN`   |   yes    | —       | Telegram Bot API token from BotFather.                                       |\n| `TELEGRAM_CHAT_ID` |   yes    | —       | Target chat ID (a user, group, or channel the bot can post to).              |\n| `LISTEN_ADDR`      |    no    | `:8080` | Address the HTTP server binds to.                                            |\n| `LOG_LEVEL`        |    no    | `info`  | One of `debug`, `info`, `warn` (or `warning`), `error` — case-insensitive.   |\n\n## Endpoints\n\n| Method | Path       | Purpose                                                                                  |\n| ------ | ---------- | ---------------------------------------------------------------------------------------- |\n| `POST` | `/webhook` | Receives a Superset notification: `application/json` (text) or `multipart/form-data` (with attachments). Any other content type returns `415`. |\n| `GET`  | `/healthz` | Liveness probe; always returns `200 OK`.                                                 |\n\n## Superset setup\n\n1. Enable alerts/reports in Superset and configure a webhook notification method.\n2. Set the webhook URL to your bridge: `http://\u003cbridge-host\u003e:8080/webhook`.\n3. Trigger an alert — a formatted message should arrive in your Telegram chat.\n\nFor an attachment-free notification Superset sends a JSON body like this (an optional `header` metadata object may also be present; unknown fields are ignored):\n\n```json\n{\n  \"name\": \"Sales dropped below threshold\",\n  \"text\": \"Daily revenue is below $10k.\",\n  \"description\": \"Fires when the daily total drops.\",\n  \"url\": \"https://superset.example.com/superset/dashboard/1/\"\n}\n```\n\nWhen a report has attachments, Superset sends `multipart/form-data` instead, and the bridge forwards the files to Telegram.\n\n### Attachments\n\n- **Routing by MIME type:** `image/png` → Telegram **photo**; everything else (CSV, PDF, …) → **document**.\n- **Single vs album:** one file of a kind is sent with `sendPhoto`/`sendDocument`; two or more of the same kind are sent as a `sendMediaGroup` album. Photos and documents are delivered as separate messages.\n- **Caption:** the rendered notification text (the same HTML body, including the **Open in Superset** link) becomes the caption, truncated to Telegram's 1024-character limit with the link always preserved.\n- **Album limit:** Telegram caps albums at 10 items _per kind_; beyond that, the first 10 are forwarded and the rest are dropped with a warning log.\n\n## Security\n\nThe bridge has no authentication on `/webhook`; it trusts its network.\n\n- Run it next to Superset — a sidecar or a container on the same private network — and let Superset reach it there (e.g. `http://bridge:8080/webhook`).\n- Don't expose it on a public or shared network.\n\nThere's no token/basic-auth option, on purpose: Superset can only put a secret in the webhook URL, which is stored in the alert config and visible to anyone who can edit alerts, so it wouldn't keep anyone out.\n\nSuperset doesn't currently restrict which hosts a webhook can target; the open PR [apache/superset#39301](https://github.com/apache/superset/pull/39301) would validate targets and block private ranges.\n\n## Local playground\n\nA self-contained Superset + bridge stack lives in [`playground/`](playground/). Seeded alerts fire every minute — text plus PNG, CSV, and PDF attachments — so you can inspect the real end-to-end payload across every path:\n\n```bash\ncd playground\ncp .env.example .env   # set TELEGRAM_TOKEN / TELEGRAM_CHAT_ID\ndocker compose up --build\n```\n\nSee [`playground/README.md`](playground/README.md) for details.\n\n## Development\n\nRequires Go 1.26+. CI runs each of these on every push.\n\n```bash\ngo build ./...\ngo vet ./...\ngo test ./... -race\ngolangci-lint run ./...   # lint + format check; config in .golangci.yml\ngovulncheck ./...         # known-vulnerability scan\n```\n\nMocks are generated with [mockery](https://vektra.github.io/mockery/) (`mockery`; config in `.mockery.yaml`).\n\n## Releasing\n\nPush a semver tag — GoReleaser builds the binaries and publishes the GitHub\nrelease (with changelog and checksums) and the GHCR image:\n\n```bash\ngit tag -a v1.2.3 -m \"v1.2.3\" \u0026\u0026 git push origin v1.2.3\n```\n\nPreview a release locally without publishing: `goreleaser release --snapshot --clean`.\n\n## License\n\n[MIT](LICENSE) © Denis Galeev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdengaleev%2Fsuperset-telegram-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdengaleev%2Fsuperset-telegram-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdengaleev%2Fsuperset-telegram-bridge/lists"}