Ko-fi Integration: Webhook-System & Alert-Overlay #61

New issue

Open

opened 2026-07-15 20:02:13 +02:00 by frank · 0 comments

frank commented

2026-07-15 20:02:13 +02:00

Owner

Kontext

Streamer nutzen Ko-fi (kofi.com) als primäre Plattform für Donations, Memberships und Shop-Verkäufe – direkt neben dem Stream. Ko-fi bietet ein Webhook-System (keine REST-Lese-API), das Zahlungsereignisse per POST an einen konfigurierbaren Endpunkt sendet.

Ko-fi Webhook: Form-encoded POST mit data-Feld (JSON). Verifizierung via verification_token. Events kommen von Ko-fi → unser System.

Mögliche Payload-Typen:

Donation/Tip — Einmalige Spende (type: "Donation")
Subscription — Monatliche Mitgliedschaft (is_subscription_payment: true)
Commission — Auftragszahlung (type: "Commission")
Shop Order — Shop-Bestellung (type: "Shop Order")

Wichtige Payload-Felder:

Feld	Typ	Beschreibung
`from_name`	string	Name des Unterstützers (leer bei privaten)
`type`	string	"Donation", "Subscription", "Commission", "Shop Order"
`amount`	string	Betrag (z.B. "5,00")
`currency`	string	Währung (z.B. "EUR")
`message`	string	Nachricht des Unterstützers
`is_public`	boolean	Öffentliche oder private Unterstützung
`is_subscription_payment`	boolean	Wiederkehrende Zahlung
`is_first_subscription_payment`	boolean	Erste Zahlung eines neuen Members
`tier_name`	string	Name des Membership-Tiers
`shop_items`	array	Bei Shop Orders: [{name, quantity, direct_link_code}]
`email`	string	E-Mail (privat)
`kofi_transaction_id`	string	Transaktions-ID

Ziel

Ein Ko-fi Webhook Server & Alert Overlay System für streamertool:

1. Webhook-Empfänger

HTTP-Endpoint in streamertool zum Empfang von Ko-fi Webhooks
Verifizierung via verification_token
Parsing des form-encoded data-Payloads
POST-only, CORS-konform
Fehlerbehandlung: 401 bei falschem Token, 400 bei invalidem Payload

2. Alert-Overlay (OBS Browser Source)

Donation/Tip Alert — Einblendung bei neuer Spende mit Name, Betrag, Nachricht
Subscription Alert — Spezielles Overlay für neue Mitgliedschaften (inkl. Tier-Name)
Commission Alert — Overlay für Commissions
Shop Order Alert — Overlay mit Bestellübersicht
Respektiert is_public Flag (Private = "Anonymer Unterstützer")
Animierte Ein-/Ausblendung
Konfigurierbare Dauer und Position
Sound-Effekt pro Event-Typ (konfigurierbar)

3. TTS-Unterstützung

Text-to-Speech für öffentliche Ko-fi Nachrichten
Konfigurierbar pro Event-Typ
Sprachauswahl

4. Dashboard-Konfiguration

Eingabe des Ko-fi Verification Tokens
Webhook-URL anzeigen (zum Eintragen bei Ko-fi)
Test-Button (sendet simulierten Webhook)
Aktivitäts-Log der letzten Events
Enable/Disable pro Event-Typ

5. Daten-Persistenz

Lokale Speicherung aller Ko-fi Transaktionen
Aggregation: Total-Einnahmen, Top-Supporter, letzte 30 Tage
Export als CSV

Technische Leitplanken

Tauri 2 Backend: Rust HTTP-Server (z.B. actix-web oder axum) oder separater Sidecar
OBS Integration: Browser-Source-Overlay (HTML/CSS/JS) via lokalen Websocket oder HTTP-Push
Konfiguration: In settings.json unter integrations.kofi
Abhängigkeiten: Keine externen Dienste außer Ko-fi Webhook selbst
Keine OAuth nötig — Ko-fi hat kein REST-API, nur Webhooks

Akzeptanz

Ko-fi Webhook-Endpoint akzeptiert POST und verifiziert Token
Alle 4 Event-Typen (Donation, Subscription, Commission, Shop) werden korrekt geparst
OBS-Overlay zeigt Alert mit Name, Betrag, Nachricht, Tier
Private Supporters werden anonymisiert dargestellt
TTS funktioniert für öffentliche Nachrichten
Dashboard zeigt Konfiguration und Aktivitäts-Log
Transaktionen werden lokal persistiert und sind exportierbar

Verwandte Issues

#30 Donation/Tip-System (übergreifend)
#62 Ko-fi Membership & Goal Widgets
#63 Patreon Integration

## Kontext Streamer nutzen **Ko-fi** (kofi.com) als primäre Plattform für Donations, Memberships und Shop-Verkäufe – direkt neben dem Stream. Ko-fi bietet ein **Webhook-System** (keine REST-Lese-API), das Zahlungsereignisse per POST an einen konfigurierbaren Endpunkt sendet. **Ko-fi Webhook:** Form-encoded POST mit `data`-Feld (JSON). Verifizierung via `verification_token`. Events kommen von Ko-fi → unser System. **Mögliche Payload-Typen:** - `Donation/Tip` — Einmalige Spende (`type: "Donation"`) - `Subscription` — Monatliche Mitgliedschaft (`is_subscription_payment: true`) - `Commission` — Auftragszahlung (`type: "Commission"`) - `Shop Order` — Shop-Bestellung (`type: "Shop Order"`) **Wichtige Payload-Felder:** | Feld | Typ | Beschreibung | |------|-----|-------------| | `from_name` | string | Name des Unterstützers (leer bei privaten) | | `type` | string | "Donation", "Subscription", "Commission", "Shop Order" | | `amount` | string | Betrag (z.B. "5,00") | | `currency` | string | Währung (z.B. "EUR") | | `message` | string | Nachricht des Unterstützers | | `is_public` | boolean | Öffentliche oder private Unterstützung | | `is_subscription_payment` | boolean | Wiederkehrende Zahlung | | `is_first_subscription_payment` | boolean | Erste Zahlung eines neuen Members | | `tier_name` | string | Name des Membership-Tiers | | `shop_items` | array | Bei Shop Orders: [{name, quantity, direct_link_code}] | | `email` | string | E-Mail (privat) | | `kofi_transaction_id` | string | Transaktions-ID | ## Ziel Ein **Ko-fi Webhook Server & Alert Overlay System** für streamertool: ### 1. Webhook-Empfänger - [ ] HTTP-Endpoint in streamertool zum Empfang von Ko-fi Webhooks - [ ] Verifizierung via `verification_token` - [ ] Parsing des form-encoded `data`-Payloads - [ ] POST-only, CORS-konform - [ ] Fehlerbehandlung: 401 bei falschem Token, 400 bei invalidem Payload ### 2. Alert-Overlay (OBS Browser Source) - [ ] **Donation/Tip Alert** — Einblendung bei neuer Spende mit Name, Betrag, Nachricht - [ ] **Subscription Alert** — Spezielles Overlay für neue Mitgliedschaften (inkl. Tier-Name) - [ ] **Commission Alert** — Overlay für Commissions - [ ] **Shop Order Alert** — Overlay mit Bestellübersicht - [ ] Respektiert `is_public` Flag (Private = "Anonymer Unterstützer") - [ ] Animierte Ein-/Ausblendung - [ ] Konfigurierbare Dauer und Position - [ ] Sound-Effekt pro Event-Typ (konfigurierbar) ### 3. TTS-Unterstützung - [ ] Text-to-Speech für öffentliche Ko-fi Nachrichten - [ ] Konfigurierbar pro Event-Typ - [ ] Sprachauswahl ### 4. Dashboard-Konfiguration - [ ] Eingabe des Ko-fi Verification Tokens - [ ] Webhook-URL anzeigen (zum Eintragen bei Ko-fi) - [ ] Test-Button (sendet simulierten Webhook) - [ ] Aktivitäts-Log der letzten Events - [ ] Enable/Disable pro Event-Typ ### 5. Daten-Persistenz - [ ] Lokale Speicherung aller Ko-fi Transaktionen - [ ] Aggregation: Total-Einnahmen, Top-Supporter, letzte 30 Tage - [ ] Export als CSV ## Technische Leitplanken - **Tauri 2 Backend**: Rust HTTP-Server (z.B. `actix-web` oder `axum`) oder separater Sidecar - **OBS Integration**: Browser-Source-Overlay (HTML/CSS/JS) via lokalen Websocket oder HTTP-Push - **Konfiguration**: In `settings.json` unter `integrations.kofi` - **Abhängigkeiten**: Keine externen Dienste außer Ko-fi Webhook selbst - **Keine OAuth nötig** — Ko-fi hat kein REST-API, nur Webhooks ## Akzeptanz - [ ] Ko-fi Webhook-Endpoint akzeptiert POST und verifiziert Token - [ ] Alle 4 Event-Typen (Donation, Subscription, Commission, Shop) werden korrekt geparst - [ ] OBS-Overlay zeigt Alert mit Name, Betrag, Nachricht, Tier - [ ] Private Supporters werden anonymisiert dargestellt - [ ] TTS funktioniert für öffentliche Nachrichten - [ ] Dashboard zeigt Konfiguration und Aktivitäts-Log - [ ] Transaktionen werden lokal persistiert und sind exportierbar ## Verwandte Issues - #30 Donation/Tip-System (übergreifend) - #62 Ko-fi Membership & Goal Widgets - #63 Patreon Integration

frank referenced this issue

2026-07-15 20:02:23 +02:00

Ko-fi Integration: Membership, Goal-Widgets & Supporter-Display #62

frank added the

area:monetization

enhancement

priority:high

labels

2026-07-15 20:03:04 +02:00

frank referenced this issue

2026-07-15 20:04:23 +02:00

Webhook-Infrastruktur: Cloudflare Tunnel für HTTPS-Webhook-Empfang #65