API-Tokens und Webhooks einrichten

Eigene Tools, Zapier, Make.com oder Custom-Backends an Fynspark anbinden — Auth, Endpoints, Limits, Webhook-Events, Signatur-Verifikation.

⏱ 8 Min Lesezeit

Was die API + Webhooks ermöglichen

Mit API-Tokens und Webhooks bindest du Fynspark an eigene Tools, Workflows oder externe Services wie Zapier, Make.com, n8n oder Custom-Backends.

Use-Cases:

Texte automatisch optimieren oder bewerten — z. B. aus deinem CMS heraus
Dokumente anlegen und aktualisieren — aus eurem Projekt-Management
Slack-Notification: Wenn eine Optimierung fertig ist → an #marketing-Channel
Custom-Dashboard: Kontingent- und Verlaufsdaten in eigenes BI-Tool ziehen

API-Tokens — Einrichtung

Schritt 1: API-Bereich öffnen

Benutzermenü unten in der Seitenleiste → API & Webhooks (/settings/api).

Schritt 2: Token erstellen

Klick „Token erstellen".

Schritt 3: Token-Metadaten

Name — z. B. „Zapier-Integration". Hilft später beim Identifizieren.
Scopes — welche Bereiche der Token nutzen darf:
- user:read — Kontoinfos, verfügbare Aktionen und Events
- content:read — Kontingente, Verlauf, Dokumente lesen
- content:write — KI-Aktionen ausführen, Dokumente anlegen/ändern/löschen
Ablauf — 7, 30, 90 (Standard) oder 365 Tage oder unbegrenzt

Pro Konto sind bis zu 20 Tokens möglich.

Schritt 4: Token kopieren

⚠️ ACHTUNG: Der Token wird nur einmal angezeigt. Sofort kopieren und an sicherem Ort speichern (Password-Manager).

Schritt 5: Im Code verwenden

Im HTTP-Header jeder API-Anfrage:

Authorization: Bearer <DEIN_TOKEN>
Content-Type: application/json

Beispiel mit curl:

curl -X GET https://workspace.fynspark.com/api/public/v1/documents \
  -H "Authorization: Bearer <DEIN_TOKEN>" \
  -H "Content-Type: application/json"

Token verwalten

Im API-Bereich siehst du alle Tokens mit Name, Scopes, Ablaufdatum und letzter Nutzung.

Der Token-String selbst wird nie wieder gezeigt — aus Sicherheitsgründen.

Token widerrufen

Wenn ein Token kompromittiert wurde (versehentlich in Git gepusht, geleakt):

„Widerrufen" → Token sofort ungültig
Alle Anfragen mit diesem Token erhalten ab dann HTTP 401
Neuen Token erstellen + in deinen Apps austauschen

Bei jedem Verdacht sofort widerrufen — Sicherheit > Komfort.

Token rotieren (Best Practice)

Regelmäßig rotieren:

Neuen Token erstellen
In allen Apps austauschen
Alten Token widerrufen

API-Endpoints

Die Basis-URL ist https://workspace.fynspark.com/api/public/v1.

Konto und Metadaten

GET /me — Kontoinfos
GET /actions — verfügbare Aktionen
GET /events — verfügbare Webhook-Events
GET /credits — Kontingente
GET /history — Nutzungs-Verlauf

Dokumente

GET /documents — Dokument-Liste
GET /documents/{id} — einzelnes Dokument
POST /documents — neues Dokument
PATCH /documents/{id} — Dokument ändern
DELETE /documents/{id} — Dokument löschen

KI-Aktionen

POST /improve und POST /auto-improve — Text optimieren
POST /score — Text bewerten
POST /variants — Varianten erzeugen
POST /hooks — Hooks erzeugen
POST /conversion — Conversion-Analyse
POST /quality — Qualitäts-Check
POST /performance/scan und POST /performance/quick — Performance-Scan

Schreibende Endpoints und KI-Aktionen setzen voraus, dass dein Plan API-Zugriff enthält.

Limits

60 Calls / Minute pro Konto — bei Überschreitung HTTP 429
API-Zugang — ab Scale: bis zu 250 API-Requests pro Tag (ebenso in Fynspark Connect); Enterprise nach Vereinbarung; Essential enthält keinen API-Zugang
Den aktuellen Stand siehst du unter /app/usage

Webhooks — Einrichtung

Webhooks sind Push-Notifications: Fynspark schickt dir per HTTP-POST eine Nachricht, sobald etwas passiert (z. B. Optimierung fertig).

Schritt 1: Webhooks-Bereich

/settings/api → Bereich Webhooks → „Neuer Webhook".

Schritt 2: Konfiguration

Endpoint-URL — wo soll Fynspark hinposten? HTTPS Pflicht (HTTP wird abgewiesen).
Events auswählen — welche Events lösen den Webhook aus?
Beschreibung (optional) — Notiz, wozu dieser Webhook dient

Pro Konto sind bis zu 10 Webhooks möglich.

Verfügbare Events

improve.completed — Optimierung abgeschlossen
score.completed — Score berechnet
variants.completed — Varianten erstellt
conversion.analyzed — Conversion-Analyse abgeschlossen
quality.checked — Qualitäts-Check abgeschlossen
hooks.generated — Hooks generiert
performance.scanned — Performance-Scan abgeschlossen
presence.scan.completed — AI-Presence-Scan abgeschlossen
content.created — Dokument erstellt
content.updated — Dokument aktualisiert
content.deleted — Dokument gelöscht
test.ping — Test-Event über den „Test"-Button (nicht abonnierbar)

Schritt 3: Speichern

Beim Speichern erhältst du ein Webhook-Secret — kopier es (wird nur einmal gezeigt). Über „Secret rotieren" erzeugst du jederzeit ein neues.

Webhook-Payload

JSON-Body mit folgender Struktur:

{
  "id": "6f1c2a9e-…",
  "event": "content.created",
  "attempt": 1,
  "created_at": "2026-06-08T14:23:00+00:00",
  "data": { }
}

Zusätzlich schickt Fynspark diese Header mit: X-Fynspark-Event, X-Fynspark-Timestamp, X-Fynspark-Signature, X-Fynspark-Webhook-Id, X-Fynspark-Delivery und X-Fynspark-Attempt.

Signatur-Verifikation (wichtig für Sicherheit)

Der Header X-Fynspark-Signature hat das Format sha256=<hex> — ein HMAC-SHA256 mit deinem Webhook-Secret über Timestamp + „." + Payload. Den Timestamp liefert der Header X-Fynspark-Timestamp.

So verifizierst du (PHP-Beispiel):

$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_FYNSPARK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_FYNSPARK_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
// Payload ist verifiziert — sicher zu verarbeiten

Dasselbe Pattern funktioniert in Node.js, Python, Ruby etc.

Test

In der Webhook-Liste: „Test" → schickt ein test.ping-Event an deinen Endpoint. Du siehst sofort Status-Code und Antwortzeit.

Status in der Webhook-Liste

Pro Webhook siehst du die letzte Zustellung und die Anzahl aufeinanderfolgender Fehler. Webhooks lassen sich jederzeit pausieren und wieder aktivieren.

Retry-Verhalten

Bei Netzwerkfehlern, Timeouts, HTTP 408/425/429 oder 5xx versucht Fynspark es erneut: insgesamt 3 Versuche (Wartezeit 15 s, 60 s, 4 min)
Andere 4xx-Antworten werden nicht wiederholt
Nach 10 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Webhook automatisch deaktiviert — nach dem Fix in /settings/api wieder aktivieren

Verfügbarkeit pro Plan

API und Webhooks sind ab Scale enthalten (Scale und Fynspark Connect: bis zu 250 API-Requests pro Tag), in Enterprise nach Vereinbarung und in Essential nicht. Die Berechtigungen werden über den aktuellen Plan gesteuert. Öffne /settings/api: Ist die Funktion für deinen Plan freigeschaltet, kannst du dort Tokens und Webhooks verwalten; andernfalls zeigt die App die erforderliche Planstufe. Bei Fynspark Connect bleiben öffentliche API-Requests ausdrücklich begrenzt, weil sie Fynspark-Infrastruktur verbrauchen.

Tipps

Tipp 1: Tokens niemals committen. Nutz .env-Variablen, niemals direkt im Code.

Tipp 2: Signatur-Verifikation IMMER prüfen. Sonst kann jemand mit deinem Endpoint Fake-Events auslösen.

Tipp 3: Webhooks idempotent designen. Bei Retry kann dasselbe Event mehrfach ankommen — das Feld id bleibt gleich, darüber erkennst du Duplikate.

Tipp 4: Test mit ngrok. Beim lokalen Entwickeln: ngrok als HTTPS-Tunnel zu localhost.

Häufige Fragen

Was, wenn mein Endpoint down ist? Jede Zustellung wird bis zu 3-mal versucht. Nach 10 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Webhook deaktiviert.

Sind lesende API-Calls auch limitiert? Ja — das Limit von 60 Calls pro Minute gilt für alle Endpoints.

Wie unterscheiden sich API + Webhooks von Zapier? Zapier kann die API + Webhooks nutzen. Direkte API ist flexibler, Zapier ist No-Code.

Gibt es offizielle SDKs? Nein, aktuell nicht. Die API ist eine schlanke REST/JSON-Schnittstelle und lässt sich mit jedem HTTP-Client ansprechen.