API-Tokens und Webhooks einrichten

Eigene Tools, Zapier, Make.com oder Custom-Backends an Fynspark anbinden — Auth, Endpoints, 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 (früher Integromat), n8n oder Custom-Backends.

Use-Cases:

Automatischer Import von Briefings aus eurem Projekt-Management
Auto-Publish: Wenn Artikel freigegeben → an WordPress posten
Slack-Notification: Wenn Kampagne fertig → an #marketing-Channel
CRM-Sync: Wenn neuer Workspace-Member → in HubSpot CRM
Custom-Dashboard: Verbrauchs-Daten in eigenes BI-Tool ziehen

API-Tokens — Einrichtung

Schritt 1: API-Bereich öffnen

Sidebar → Einstellungen → API (/settings/api).

Schritt 2: Token erstellen

Klick „Token erstellen".

Schritt 3: Token-Metadaten

Name — z. B. „Zapier-Integration" oder „WordPress-Auto-Publish". Hilft später beim Identifizieren.
Scope — welche Bereiche der API darf dieser Token? (z. B. nur lesen, nur Knowledge schreiben)
Ablauf (optional) — z. B. „läuft in 90 Tagen ab" für Rotations-Pflicht
IP-Allowlist (Premium) — Token nur aus bestimmten IP-Bereichen nutzbar

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://api.fynspark.com/v1/usage/overview \
  -H "Authorization: Bearer fy_live_abc123def456..." \
  -H "Content-Type: application/json"

Token verwalten

Liste aller Tokens

Im API-Bereich siehst du alle aktiven Tokens mit:

Name
Letzte Nutzung (Datum)
Anzahl Calls in dieser Periode
Status (aktiv / abgelaufen)

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

Token revoken

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

„Revoken" → 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 revoken — Sicherheit > Komfort.

Token rotieren (Best Practice)

Quartalsweise Token rotieren:

Neuen Token erstellen
In allen Apps austauschen
Alten Token revoken

So verhindert ihr, dass jemals ein „uralter Token" durch alte Backups o. ä. wiederauftaucht.

API-Endpoints (Auszug)

Vollständige Doku unter /api/docs oder als Postman-Collection downloadbar.

Lesende Endpoints

GET /v1/usage/overview — aktueller Verbrauchsstand
GET /v1/documents — Dokument-Liste
GET /v1/documents/{id} — einzelnes Dokument
GET /v1/brand-voices — Brand Voices
GET /v1/campaigns — Kampagnen
GET /v1/knowledge-assets — Knowledge-Assets

Schreibende Endpoints

POST /v1/documents — neues Dokument
POST /v1/improve — Improve-Engine-Call
POST /v1/hooks — Hook-Generator-Call
POST /v1/images — Bild-Generation
POST /v1/knowledge-assets — neues Asset

Rate-Limits

100 Calls / Minute pro Token
10.000 Calls / Tag (je nach Plan höher)
Bei Überschreitung: HTTP 429 mit Retry-After-Header

Webhooks — Einrichtung

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

Schritt 1: Webhooks-Tab

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

Schritt 2: Konfiguration

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

Verfügbare Events

document.created — neues Dokument
document.updated — Dokument geändert
document.published — als veröffentlicht markiert
improve.completed — Improve-Run fertig
article.completed — Article-Assistant-Run fertig
campaign.created — neue Kampagne
campaign.approved — Kampagne freigegeben
approval.requested — Freigabe angefragt
approval.granted — Freigabe erteilt
usage.threshold_reached — Verbrauchs-Warnung (75/90/100 %)
subscription.changed — Plan geändert
member.added — neues Workspace-Mitglied

Schritt 3: Speichern

Beim Speichern erhältst du einen Webhook-Secret — kopier ihn (wird nur einmal gezeigt).

Webhook-Payload

Format: JSON-Body mit folgender Struktur:

{
  "event": "document.created",
  "timestamp": "2026-06-08T14:23:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "id": "doc_xyz789",
    "title": "Neue Pressemitteilung",
    "created_by": "user_456",
    "url": "https://workspace.fynspark.com/editor/doc_xyz789"
  }
}

Signatur-Verifikation (wichtig für Sicherheit)

Wir liefern den Header X-Fynspark-Signature mit jedem Webhook — ein HMAC-SHA256 über den Payload mit deinem Webhook-Secret.

So verifizierst du (PHP-Beispiel):

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

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

Dasselbe Pattern für Node.js, Python, Ruby etc. — Details in der API-Doku.

Test

In der Webhook-Liste: „Test-Event senden" → schickt ein Beispiel-Event an deinen Endpoint zur Verifizierung der Anbindung.

Webhook-Logs

Pro Webhook siehst du:

Letzte 20 Deliveries mit Status-Code (200 / 4xx / 5xx)
Payload-Inhalt
Response von deinem Server
Latenz (in ms)

Praktisch beim Debugging.

Retry-Verhalten

Bei Non-2xx-Response: Fynspark retry mit exponential Backoff (1 Min → 5 Min → 30 Min → 2 h → 12 h)
Nach 5 fehlgeschlagenen Versuchen: Webhook auto-deaktiviert + Mail-Notification

Verfügbarkeit pro Plan

Plan	API-Zugriff	Webhooks	Custom-Domains
Free	❌	❌	❌
Lite	❌	❌	❌
Standard	✅	✅	❌
Premium	✅	✅	❌
Business	✅	✅	✅ (Custom-Domain für Webhook-Endpoints)

Verbrauch

API-Calls zählen als api_calls Usage-Einheit
Webhook-Deliveries als webhook_deliveries
Beides hat hohe Limits — typisch nicht limitierend außer bei massiver Nutzung

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 triggern.

Tipp 3: Webhooks idempotent designen. Bei Retry wird dasselbe Event mehrfach geschickt — dein Handler sollte das verkraften.

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

Tipp 5: Beim Provider-Wechsel Webhooks aktualisieren. Wenn euer Hosting umzieht: Webhook-Endpoint sofort aktualisieren.

Häufige Fragen

Was, wenn mein Endpoint down ist? Retry-Strategie greift — bis zu 5 Versuche über 12 Stunden. Danach Webhook auto-deaktiviert.

Kann ich einen Webhook von mehreren Workspaces empfangen? Pro Webhook ein Workspace. Bei mehreren Workspaces: pro Workspace einen Webhook anlegen (oder im Handler das workspace_id-Feld unterscheiden).

Sind API-Calls in der Read-Operation auch limitiert? Ja — gleicher Rate-Limit wie Schreib-Operations.

Wie unterscheiden sich API + Webhooks von Zapier? Zapier nutzt die API + Webhooks unter der Haube. Direkte API ist flexibler, Zapier ist No-Code.

Bietet Fynspark einen offiziellen SDK? Aktuell: Postman-Collection. Offizielle SDKs für Node.js, Python, PHP sind auf der Roadmap.