https://github.com/jedbillyb/posthog-notify
FastAPI webhook receiver that forwards PostHog events to Telegram
https://github.com/jedbillyb/posthog-notify
fastapi notifications posthog python self-hosted systemd telegram vps webhook
Last synced: about 7 hours ago
JSON representation
FastAPI webhook receiver that forwards PostHog events to Telegram
- Host: GitHub
- URL: https://github.com/jedbillyb/posthog-notify
- Owner: jedbillyb
- License: mit
- Created: 2026-04-21T11:41:24.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-06-04T09:52:36.000Z (27 days ago)
- Last Synced: 2026-06-04T11:13:23.429Z (27 days ago)
- Topics: fastapi, notifications, posthog, python, self-hosted, systemd, telegram, vps, webhook
- Language: Python
- Homepage:
- Size: 15.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# posthog-telegram
**Forwards PostHog webhook events to Telegram in real-time.**
[](./LICENSE)
[](https://www.python.org)
[](https://posthog.com)
---
A lightweight FastAPI webhook receiver. PostHog pushes events to `/posthog`, the service filters noise, extracts key properties, and fires a formatted message to Telegram. Designed to run as a systemd service on a VPS.
## Features
- **Webhook-driven** — Zero polling; PostHog pushes events instantly
- **Noise filtering** — Configurable `SKIP_EVENTS` set drops web vitals, autocapture, and other noise
- **Rich formatting** — Site label, event name, timestamp, location, URL, and device info per message
- **vehiclefinder-aware** — Extracts `make`, `model`, and `year` for vehicle search events
- **Fuzzy property matching** — Handles inconsistent PostHog key casing and formatting automatically
## Stack
| Layer | Tech |
|---|---|
| Language | Python 3.10+ |
| Web framework | FastAPI |
| HTTP client | requests |
| APIs | PostHog Webhooks, Telegram Bot API |
| Process management | systemd |
| Config | `.env` via `python-dotenv` |
## Getting Started
```bash
git clone https://github.com/jedbillyb/posthog-telegram.git
cd posthog-telegram
python3 -m venv venv
venv/bin/pip install -r requirements.txt
cp .env.example .env
```
Fill in `.env`:
```env
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
```
**Getting your Telegram chat ID:** message your bot, then visit `https://api.telegram.org/bot/getUpdates`.
Run locally:
```bash
venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000
```
### PostHog setup
In PostHog → **Project Settings** → **Webhooks**, add your endpoint:
```
https://your-domain.com/posthog
```
## Deployment
Copy to your VPS and install the systemd service:
```bash
scp -r . ubuntu@server.jedbillyb.com:/opt/posthog-telegram
ssh ubuntu@server.jedbillyb.com
cd /opt/posthog-telegram
python3 -m venv venv
venv/bin/pip install -r requirements.txt
nano .env # fill in your keys
sudo cp posthog-telegram.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now posthog-telegram
sudo journalctl -u posthog-telegram -f
```
The service must be reachable from the internet — proxy it through nginx or Caddy on your VPS.
## Message Format
```
VF · Pageview 14:32:01 UTC
abc12345… · Auckland, New Zealand
/stats/toyota?make=toyota
Chrome · Mac OS X
```
For vehicle search events, a vehicle line is prepended:
```
VF · Pageview 14:32:01 UTC
2018 Toyota Corolla
abc12345… · Wellington, New Zealand
/search
Chrome · Windows
```
---