Webhook-Receiver-API: HTTP-Endpunkte für Ko-fi, Patreon, PayPal #66

New issue

Open

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

frank commented

2026-07-15 20:05:55 +02:00

Owner

Kontext

Streamertool benötigt einen Webhook-Receiver-Server, der HTTP-POST-Requests von externen Diensten entgegennimmt, validiert, parst und an den Event-Bus weiterleitet. Dieser Server läuft auf localhost:3443 und wird über Cloudflare Tunnel (#65) öffentlich erreichbar gemacht.

Ziel

Ein dedizierter HTTP-Server (Rust, Actix Web / Axum) auf Port 3443 mit folgenden Endpunkten:

1. Webhook-Router

Endpunkt	Dienst	Methode	Beschreibung
`/webhooks/kofi`	Ko-fi	POST	Ko-fi Donations, Commissions, Shop, Subscriptions
`/webhooks/patreon`	Patreon	POST	Patreon Members, Pledges, Goals, Tiers
`/webhooks/paypal`	PayPal IPN	POST	PayPal Zahlungsbenachrichtigungen
`/webhooks/stripe`	Stripe	POST	Stripe Payment Intents, Subscriptions
`/health`	—	GET	Health-Check (wird von Cloudflare Tunnel genutzt)

2. Service-Implementierungen

Ko-fi Webhook (`/webhooks/kofi`)

Empfängt POST mit JSON-Body ({"data": {...}, "event": "..."})
Verifiziert via Ko-fi Secret (HMAC-SHA256)
Event-Typen: Donation, Subscription, ShopOrder, Commission
Extrahiert: Name, Betrag, Währung, Nachricht, is_public, Tier
Leitet als kofi.donation, kofi.subscription, kofi.shop_order, kofi.commission an Event-Bus

Patreon Webhook (`/webhooks/patreon`)

Empfängt POST mit JSON-Body (Patreon API v2 Format)
Verifiziert via Patreon Webhook Secret (HMAC-SHA256)
Event-Typen: members:create, members:update, members:delete, pledge:create, etc.
Extrahiert: Patron-Name, Tier, Betrag, Status
Leitet als patreon.* Events an Event-Bus

PayPal IPN (`/webhooks/paypal`)

Empfängt POST mit Form-Daten (IPN-Format)
Verifiziert via PayPal IPN-Verification (POST zurück an PayPal)
Event-Typen: payment_status=Completed, txn_type=web_accept, subscr_*
Extrahiert: Name, Betrag, Währung, Transaktions-ID
Leitet als paypal.donation, paypal.subscription an Event-Bus

Stripe Webhook (`/webhooks/stripe`) — Zukunft

Empfängt POST mit JSON-Body
Verifiziert via Stripe Webhook Secret
Leitet als stripe.* Events an Event-Bus

3. Gemeinsame Infrastruktur

Signature Validation: Jeder Dienst hat eigene Verifikationslogik
Rate Limiting: Max 100 Requests/Minute pro Endpunkt (DDoS-Schutz)
Request Logging: Alle eingehenden Requests werden geloggt (Datum, Dienst, IP, Status)
Error Responses: Einheitliche Fehlerantworten (400 bei Validation-Fail, 200 bei OK)
Idempotency: Duplikaterkennung via Webhook-ID (falls vom Dienst gesendet)

4. Dashboard

Übersicht: Welche Dienste sind aktiviert (Ko-fi/Patréon/PayPal)
Letzte 50 Webhook-Events (Typ, Status, Zeit, Payload-Vorschau)
Webhook-URLs anzeigen (z.B. https://webhooks.streamertool.app/webhooks/kofi)
Signature-Secret Konfiguration pro Dienst
Enable/Disable für einzelne Dienste
Test-Webhook senden (simuliert einen Event für Testzwecke)

Technische Leitplanken

Port: 3443 (dediziert, nicht Overlay-Server-Port)
Framework: Rust (Actix Web oder Axum) — separate Binary oder integriert in Tauri-Backend
Event-Bus: Webhook-Events werden an den globalen Event-Bus übergeben (gleiche Queue wie Overlay-Events)
Secrets: Werden in macOS Keychain gespeichert, nicht in settings.json
Konfiguration: Unter settings.json → webhooks.receiver
Startreihenfolge: App-Start → Webhook-Server (:3443) → Cloudflare Tunnel (#65) → Health-Check
TLS: Nicht nötig — Cloudflare Tunnel terminiert TLS (#65)
Dokumentation: ADR im Wiki (siehe /wiki/ADR-001-Cloudflare-Tunnel)

Akzeptanzkriterien

Ko-fi-Webhook wird empfangen, validiert und an Event-Bus weitergeleitet
Patreon-Webhook wird empfangen, validiert und an Event-Bus weitergeleitet
PayPal IPN wird empfangen, validiert und an Event-Bus weitergeleitet
Dashboard zeigt Webhook-URLs, letzte Events und Konfiguration
Alle Secrets werden sicher in der Keychain gespeichert
Health-Check-Endpunkt antwortet mit 200 OK
Signature-Validation schlägt fehl wenn Secret nicht stimmt (401)

Verwandte Issues

#65 Cloudflare Tunnel (VORAUSSETZUNG)
#61 Ko-fi Webhook-System
#63 Patreon OAuth & Alert-Overlay
#30 Donation/Tip-System

## Kontext Streamertool benötigt einen **Webhook-Receiver-Server**, der HTTP-POST-Requests von externen Diensten entgegennimmt, validiert, parst und an den Event-Bus weiterleitet. Dieser Server läuft auf `localhost:3443` und wird über Cloudflare Tunnel (#65) öffentlich erreichbar gemacht. ## Ziel Ein dedizierter HTTP-Server (Rust, Actix Web / Axum) auf Port `3443` mit folgenden Endpunkten: ### 1. Webhook-Router | Endpunkt | Dienst | Methode | Beschreibung | |----------|--------|---------|-------------| | `/webhooks/kofi` | Ko-fi | POST | Ko-fi Donations, Commissions, Shop, Subscriptions | | `/webhooks/patreon` | Patreon | POST | Patreon Members, Pledges, Goals, Tiers | | `/webhooks/paypal` | PayPal IPN | POST | PayPal Zahlungsbenachrichtigungen | | `/webhooks/stripe` | Stripe | POST | Stripe Payment Intents, Subscriptions | | `/health` | — | GET | Health-Check (wird von Cloudflare Tunnel genutzt) | ### 2. Service-Implementierungen #### Ko-fi Webhook (`/webhooks/kofi`) - [ ] Empfängt POST mit JSON-Body (`{"data": {...}, "event": "..."}`) - [ ] Verifiziert via Ko-fi Secret (HMAC-SHA256) - [ ] Event-Typen: `Donation`, `Subscription`, `ShopOrder`, `Commission` - [ ] Extrahiert: Name, Betrag, Währung, Nachricht, is_public, Tier - [ ] Leitet als `kofi.donation`, `kofi.subscription`, `kofi.shop_order`, `kofi.commission` an Event-Bus #### Patreon Webhook (`/webhooks/patreon`) - [ ] Empfängt POST mit JSON-Body (Patreon API v2 Format) - [ ] Verifiziert via Patreon Webhook Secret (HMAC-SHA256) - [ ] Event-Typen: `members:create`, `members:update`, `members:delete`, `pledge:create`, etc. - [ ] Extrahiert: Patron-Name, Tier, Betrag, Status - [ ] Leitet als `patreon.*` Events an Event-Bus #### PayPal IPN (`/webhooks/paypal`) - [ ] Empfängt POST mit Form-Daten (IPN-Format) - [ ] Verifiziert via PayPal IPN-Verification (POST zurück an PayPal) - [ ] Event-Typen: `payment_status=Completed`, `txn_type=web_accept`, `subscr_*` - [ ] Extrahiert: Name, Betrag, Währung, Transaktions-ID - [ ] Leitet als `paypal.donation`, `paypal.subscription` an Event-Bus #### Stripe Webhook (`/webhooks/stripe`) — Zukunft - [ ] Empfängt POST mit JSON-Body - [ ] Verifiziert via Stripe Webhook Secret - [ ] Leitet als `stripe.*` Events an Event-Bus ### 3. Gemeinsame Infrastruktur - [ ] **Signature Validation**: Jeder Dienst hat eigene Verifikationslogik - [ ] **Rate Limiting**: Max 100 Requests/Minute pro Endpunkt (DDoS-Schutz) - [ ] **Request Logging**: Alle eingehenden Requests werden geloggt (Datum, Dienst, IP, Status) - [ ] **Error Responses**: Einheitliche Fehlerantworten (400 bei Validation-Fail, 200 bei OK) - [ ] **Idempotency**: Duplikaterkennung via Webhook-ID (falls vom Dienst gesendet) ### 4. Dashboard - [ ] Übersicht: Welche Dienste sind aktiviert (Ko-fi/Patréon/PayPal) - [ ] Letzte 50 Webhook-Events (Typ, Status, Zeit, Payload-Vorschau) - [ ] Webhook-URLs anzeigen (z.B. `https://webhooks.streamertool.app/webhooks/kofi`) - [ ] Signature-Secret Konfiguration pro Dienst - [ ] Enable/Disable für einzelne Dienste - [ ] Test-Webhook senden (simuliert einen Event für Testzwecke) ## Technische Leitplanken - **Port**: `3443` (dediziert, nicht Overlay-Server-Port) - **Framework**: Rust (Actix Web oder Axum) — separate Binary oder integriert in Tauri-Backend - **Event-Bus**: Webhook-Events werden an den globalen Event-Bus übergeben (gleiche Queue wie Overlay-Events) - **Secrets**: Werden in macOS Keychain gespeichert, nicht in `settings.json` - **Konfiguration**: Unter `settings.json` → `webhooks.receiver` - **Startreihenfolge**: App-Start → Webhook-Server (`:3443`) → Cloudflare Tunnel (#65) → Health-Check - **TLS**: Nicht nötig — Cloudflare Tunnel terminiert TLS (#65) - **Dokumentation**: ADR im Wiki (siehe `/wiki/ADR-001-Cloudflare-Tunnel`) ## Akzeptanzkriterien - [ ] Ko-fi-Webhook wird empfangen, validiert und an Event-Bus weitergeleitet - [ ] Patreon-Webhook wird empfangen, validiert und an Event-Bus weitergeleitet - [ ] PayPal IPN wird empfangen, validiert und an Event-Bus weitergeleitet - [ ] Dashboard zeigt Webhook-URLs, letzte Events und Konfiguration - [ ] Alle Secrets werden sicher in der Keychain gespeichert - [ ] Health-Check-Endpunkt antwortet mit 200 OK - [ ] Signature-Validation schlägt fehl wenn Secret nicht stimmt (401) ## Verwandte Issues - #65 Cloudflare Tunnel **(VORAUSSETZUNG)** - #61 Ko-fi Webhook-System - #63 Patreon OAuth & Alert-Overlay - #30 Donation/Tip-System

frank added the

labels

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

frank referenced this issue

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

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

frank added

effort:medium