🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowSaas API - für Portale, Ideen und die Roadmap

Eine vollständige REST API für die öffentlichen Feedback-Portale. Ideen anlegen und beantworten, den Status pflegen, Beiträge und Kommentare moderieren, die Roadmap füllen und andere Systeme über Webhooks auf dem Laufenden halten. Die öffentlichen Portalseiten unter /p/{slug} bleiben davon unberührt.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowsaas/context https://creativeskyline.de/api/flowsaas/portals https://creativeskyline.de/api/flowsaas/posts https://creativeskyline.de/api/flowsaas/roadmap-items https://creativeskyline.de/api/flowsaas/reports/moderation
FlowSaas-Berechtigung erforderlich
Der Benutzer benötigt eine aktive FlowSaas-Berechtigung. Ist das Modul in den Teameinstellungen abgeschaltet, antwortet jede Route mit HTTP 403.
Alles wird über UUIDs adressiert
Portal, Idee, Kommentar, Status, Schlagwort, Roadmap-Eintrag und Webhook werden ausschließlich über ihre UUID angesprochen. Numerische Felder wie portal_id oder status_id werden nicht entgegengenommen und führen zu einem Validierungsfehler, der das Ersatzfeld benennt.
Verwaltungsberechtigung für alles, was die Öffentlichkeit sieht
Der Modulzugriff allein erlaubt keine Moderation und keine Löschung. Ideen und Kommentare freigeben, ablehnen oder als Spam markieren, Portale, Status, Schlagwörter und Roadmap-Einträge löschen, ein Portal erreichbar schalten und alles rund um Webhooks setzt die Verwaltungsberechtigung voraus: Inhaberschaft, das Recht zur Teamverwaltung oder ein Plattform-Administrator. Fehlt sie, antwortet die Route mit HTTP 403.

1. API-Zugangsdaten abrufen

Melden Sie sich an, öffnen Sie Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Authentifizierung

Alle Anfragen benötigen diese HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

3. Einstieg

Beginnen Sie mit GET /api/flowsaas/context. Die Antwort nennt alle Portale des Teams mit ihren Status und Schlagwörtern, die offenen Moderationszahlen und ob dieser Schlüssel die Verwaltungsberechtigung besitzt.

4. Antwortformat

Erfolgreiche Anfragen antworten mit {"success": true, "data": ...}. Listen tragen zusätzlich meta mit current_page, per_page, total und last_page. Fehler antworten mit {"success": false, "error": "...", "message": "..."}.

🧭 Überblick und Auswertungen

Portale, Vokabular und eigene Rechte abrufen

GET /api/flowsaas/context

Liefert alle Portale des Teams mit Status, Schlagwörtern und offenen Moderationszahlen, dazu die möglichen Moderationszustände, die verfügbaren Webhook-Ereignisse und ob dieser Schlüssel die Verwaltungsberechtigung besitzt.

Offene Moderation abrufen

GET /api/flowsaas/reports/moderation

Zählt die wartenden Ideen und Kommentare aller Portale des Teams und liefert je bis zu zwanzig davon, neueste zuerst.

Beliebteste Ideen abrufen

GET /api/flowsaas/reports/top-ideas

Die zwanzig freigegebenen Ideen mit den meisten Stimmen. Zusammengeführte Ideen bleiben außen vor, ihre Stimmen zählen bei der Idee, in die sie übernommen wurden.

Veröffentlichte Roadmap abrufen

GET /api/flowsaas/reports/roadmap

Die ersten fünfzig Roadmap-Einträge aller Portale in ihrer veröffentlichten Reihenfolge, jeweils mit Titel, Spalte und Stimmenzahl der dahinterliegenden Idee.

Aktivität der letzten 30 Tage abrufen

GET /api/flowsaas/reports/activity

Zählt neue Ideen und Kommentare der letzten dreißig Tage und liefert die zehn jüngsten Ideen dazu.

🏠 Portale

Ein neues Portal bringt sein Vokabular mit
Beim Anlegen entstehen fünf Status (Feedback, Backlog, Planung, In Arbeit, Fertig) und vier Schlagwörter. Sie lassen sich anschließend umbenennen, umsortieren und ergänzen.
is_public, is_active und seo_indexable sind Verwaltungssache
Diese drei Schalter entscheiden, ob und wie das Portal im Internet erreichbar ist. Eine Änderung an einem davon setzt die Verwaltungsberechtigung voraus, auch wenn sie zusammen mit gewöhnlichen Feldern gesendet wird.

Portale auflisten

GET /api/flowsaas/portals

Alle Portale des Teams, neueste zuerst, mit der Zahl ihrer Ideen und der wartenden Beiträge.

Query-Parameter:

search string Sucht in Name und Adresse des Portals.
is_active boolean Nur eingeschaltete beziehungsweise nur abgeschaltete Portale.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitenzahl, Standard 1.

Portal anlegen

POST /api/flowsaas/portals

Legt ein Portal im Team des API-Schlüssels an, samt der fünf Standard-Status und der vier Standard-Schlagwörter. Verlangt die Verwaltungsberechtigung.

Request Body:

name string * Anzeigename, mindestens drei Zeichen.
slug string Öffentliche Adresse unter /p/. Muss installationsweit eindeutig sein; ohne Angabe aus dem Namen abgeleitet.
description string Kurzbeschreibung für die Portalseite.
is_public boolean Ob das Portal öffentlich erreichbar ist. Standard true.
subdomain string Eigene Subdomain. Ohne Angabe wird der Slug übernommen.
default_language string de oder en. Standard de.

Portal abrufen

GET /api/flowsaas/portals/{uuid}

Ein Portal mit seinen Status, seinen Schlagwörtern und den offenen Moderationszahlen.

Portal ändern

PUT /api/flowsaas/portals/{uuid}

Ändert die gesendeten Felder; alles Übrige bleibt unangetastet. Enthält die Anfrage is_public, is_active oder seo_indexable, ist die Verwaltungsberechtigung nötig.

Request Body:

name string Anzeigename.
slug string Öffentliche Adresse. Eine Änderung bricht bestehende Links.
description string Kurzbeschreibung.
is_public boolean Öffentliche Erreichbarkeit. Verwaltungsberechtigung nötig.
is_active boolean Portal ein- oder ausschalten. Verwaltungsberechtigung nötig.
seo_indexable boolean Indexierung durch Suchmaschinen. Verwaltungsberechtigung nötig.
subdomain string Eigene Subdomain.
custom_domain string Eigene Domain.
dark_mode_enabled boolean Dunkler Modus im Portal.
default_language string de oder en.
voting_without_auth boolean Abstimmen ohne Anmeldung erlauben.
post_approval_required boolean Neue Ideen erst nach Freigabe zeigen.
comment_approval_required boolean Neue Kommentare erst nach Freigabe zeigen.
allow_anonymous_read boolean Lesen ohne Anmeldung erlauben.
lock_completed_ideas boolean Abgeschlossene Ideen für Kommentare sperren.
tag_limit integer Höchstzahl Schlagwörter je Idee. 0 bedeutet keine Grenze.

Portal löschen

DELETE /api/flowsaas/portals/{uuid}

Löscht das Portal mit allen Ideen, Stimmen, Kommentaren, Status, Schlagwörtern, Roadmap-Einträgen und Webhooks. Verlangt die Verwaltungsberechtigung und ist nicht umkehrbar.

Portal ein- oder ausschalten

POST /api/flowsaas/portals/{uuid}/toggle-active

Kehrt den Schalter is_active um, ohne etwas im Portal zu verändern. Verlangt die Verwaltungsberechtigung.

Alle Ideen eines Portals löschen

POST /api/flowsaas/portals/{uuid}/delete-all-ideas

Löscht jede Idee des Portals mit ihren Stimmen, Kommentaren, Verlauf und Roadmap-Einträgen. Das Portal selbst und sein Vokabular bleiben bestehen. Verlangt die Verwaltungsberechtigung und ist nicht umkehrbar.

Erscheinungsbild abrufen

GET /api/flowsaas/portals/{uuid}/company

Logos, Farbgebung und Anzeigename des Portals. Ein Portal ohne gepflegtes Erscheinungsbild antwortet mit seiner UUID und sonst leeren Feldern.

Erscheinungsbild ändern

PUT /api/flowsaas/portals/{uuid}/company

Schreibt die gesendeten Felder und legt den Datensatz bei der ersten Änderung an. Die Bildfelder erwarten fertige Adressen; die Schnittstelle lädt selbst keine Datei herunter.

Request Body:

name string Angezeigter Name im Portalkopf.
logo_url string Adresse des Logos für den hellen Modus.
logo_dark_url string Adresse des Logos für den dunklen Modus.
logo_landscape_url string Adresse des Querformat-Logos.
logo_landscape_dark_url string Adresse des Querformat-Logos für den dunklen Modus.
logo_layout_mode string square oder landscape.
logo_display_mode string logo_and_name oder logo_only.
logo_link string Ziel, auf das das Logo verweist.
favicon_url string Adresse des Favicons.
open_graph_image_url string Adresse des Vorschaubildes für soziale Netzwerke.
primary_color string Akzentfarbe als Hex-Wert, etwa #6392D9.

🏷️ Status und Schlagwörter

Der Status ist zugleich die Roadmap-Spalte
Jede Idee zeigt einen Status, und die Roadmap gruppiert ihre Einträge nach genau diesem Status. Ein neuer Status erzeugt damit auch eine neue Spalte.
Der letzte Status bleibt
Beim Löschen eines Status wandern alle betroffenen Ideen auf den ersten verbleibenden. Der letzte Status eines Portals lässt sich nicht löschen und die Anfrage antwortet mit HTTP 422 und error last_status.

Status eines Portals auflisten

GET /api/flowsaas/portals/{uuid}/statuses

Alle Status des Portals in ihrer eigenen Reihenfolge. Die Liste ist nicht seitenweise, sie ist immer vollständig.

Status anlegen

POST /api/flowsaas/portals/{uuid}/statuses

Hängt einen Status an das Ende der Liste des Portals.

Request Body:

name string * Anzeigename des Status.
color string Farbe als sechsstelliger Hex-Wert, etwa #6392D9.
is_completed boolean Markiert den Status als Abschluss. Zusammen mit lock_completed_ideas sperrt er die Kommentare.
sort_order integer Position in der Liste. Ohne Angabe ans Ende.

Status umsortieren

POST /api/flowsaas/portals/{uuid}/statuses/reorder

Setzt die Reihenfolge der Status des Portals auf die gesendete Liste. UUIDs anderer Portale desselben Teams werden übergangen.

Request Body:

status_uuids array * Die Status-UUIDs in der gewünschten Reihenfolge.

Status ändern

PUT /api/flowsaas/statuses/{uuid}

Ändert Name, Farbe, Abschlusskennzeichen oder Position eines Status.

Request Body:

name string Anzeigename.
color string Sechsstelliger Hex-Wert.
is_completed boolean Abschlusskennzeichen.
sort_order integer Position in der Liste.

Status löschen

DELETE /api/flowsaas/statuses/{uuid}

Löscht den Status und hängt jede Idee, die ihn trug, auf den ersten verbleibenden Status des Portals um. Verlangt die Verwaltungsberechtigung.

Schlagwörter eines Portals auflisten

GET /api/flowsaas/portals/{uuid}/tags

Alle Schlagwörter des Portals in ihrer eigenen Reihenfolge, auch die zurückgezogenen.

Schlagwort anlegen

POST /api/flowsaas/portals/{uuid}/tags

Hängt ein Schlagwort an das Ende der Liste des Portals.

Request Body:

name string * Anzeigename des Schlagworts.
description string Erläuterung für die Portalseite.
is_active boolean Ob das Schlagwort angeboten wird. Standard true.
sort_order integer Position in der Liste. Ohne Angabe ans Ende.

Schlagwörter umsortieren

POST /api/flowsaas/portals/{uuid}/tags/reorder

Setzt die Reihenfolge der Schlagwörter des Portals auf die gesendete Liste. UUIDs anderer Portale desselben Teams werden übergangen.

Request Body:

tag_uuids array * Die Schlagwort-UUIDs in der gewünschten Reihenfolge.

Schlagwort ändern

PUT /api/flowsaas/tags/{uuid}

Ändert Name, Erläuterung, Position oder ob das Schlagwort noch angeboten wird. Ein zurückgezogenes Schlagwort bleibt an jeder Idee, die es trägt.

Request Body:

name string Anzeigename.
description string Erläuterung.
is_active boolean Ob das Schlagwort angeboten wird.
sort_order integer Position in der Liste.

Schlagwort löschen

DELETE /api/flowsaas/tags/{uuid}

Löscht das Schlagwort; die Zuordnung verschwindet damit an jeder Idee, die es trug. Verlangt die Verwaltungsberechtigung.

💡 Ideen

Über die API angelegte Ideen sind sofort freigegeben
Eine Idee, die über diesen Weg entsteht, gilt als von einem Teammitglied geschrieben und wird dem Benutzer des API-Schlüssels zugeschrieben. Sie durchläuft keine Moderation. Ideen von Besuchern entstehen weiterhin auf der Portalseite und folgen dort der Einstellung post_approval_required.
Ein Statuswechsel benachrichtigt die Unterstützer
PUT auf /status schreibt einen Verlaufseintrag, löst die Portal-Webhooks aus und verschickt eine Nachricht an alle, die für die Idee gestimmt haben. Deshalb ist der Status kein Feld der gewöhnlichen Änderung.

Ideen auflisten

GET /api/flowsaas/posts

Die Ideen aller Portale des Teams. Zusammengeführte Ideen bleiben außen vor, sofern include_merged nicht gesetzt ist.

Query-Parameter:

portal_uuid string Auf ein Portal einschränken.
status_uuid string Nur Ideen in diesem Status.
tag_uuid string Nur Ideen mit diesem Schlagwort.
moderation_status string pending, approved, rejected oder spam.
search string Sucht in Titel und Text der Idee.
is_private boolean Nur verborgene beziehungsweise nur sichtbare Ideen.
is_on_roadmap boolean Nur Ideen auf der Roadmap.
include_merged boolean Zusammengeführte Ideen mit aufnehmen.
sort string newest, oldest, votes oder comments. Standard newest.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitenzahl, Standard 1.

Idee anlegen

POST /api/flowsaas/posts

Legt eine Idee im genannten Portal an, zugeschrieben an den Benutzer des API-Schlüssels und sofort freigegeben. Ohne Statusangabe landet sie im ersten Status des Portals, ohne Schlagwörter erhält sie das erste angebotene.

Request Body:

portal_uuid string * Das Portal, in dem die Idee entsteht.
title string * Titel, mindestens drei Zeichen.
body string Beschreibung der Idee.
status_uuid string Status des Portals. Ein Status eines anderen Portals wird übergangen.
tag_uuids array Schlagwörter des Portals. Die Grenze tag_limit des Portals gilt.
is_private boolean Die Idee vor Besuchern verbergen.
is_on_roadmap boolean Zugleich einen Roadmap-Eintrag anlegen.

Idee abrufen

GET /api/flowsaas/posts/{uuid}

Eine Idee mit ihren Schlagwörtern und ihrem vollständigen Statusverlauf.

Idee ändern

PUT /api/flowsaas/posts/{uuid}

Ändert die gesendeten Felder. Der Status gehört nicht dazu, er hat einen eigenen Endpunkt. Eine leere Liste tag_uuids nimmt alle Schlagwörter ab.

Request Body:

title string Titel.
body string Beschreibung.
is_private boolean Sichtbarkeit für Besucher.
is_pinned boolean Die Idee oben anheften.
is_archived boolean Die Idee archivieren.
tag_uuids array Die Schlagwörter, die danach gelten sollen.

Idee löschen

DELETE /api/flowsaas/posts/{uuid}

Löscht die Idee mit ihren Stimmen, Kommentaren und ihrem Verlauf. Verlangt die Verwaltungsberechtigung.

Status einer Idee ändern

PUT /api/flowsaas/posts/{uuid}/status

Setzt die Idee auf einen anderen Status ihres eigenen Portals. Schreibt einen Verlaufseintrag, löst die Portal-Webhooks aus und benachrichtigt alle Unterstützer. Ein Status eines anderen Portals antwortet mit HTTP 422 und error status_not_in_portal.

Request Body:

status_uuid string * Der neue Status, aus dem Portal der Idee.
comment string Begründung, die im Verlauf festgehalten wird.

Idee freigeben

POST /api/flowsaas/posts/{uuid}/approve

Gibt eine wartende Idee für das Portal frei und benachrichtigt die verfassende Person. Verlangt die Verwaltungsberechtigung.

Idee ablehnen

POST /api/flowsaas/posts/{uuid}/reject

Lehnt eine Idee ab. Die Begründung wird gespeichert und erreicht die verfassende Person mit der Benachrichtigung. Verlangt die Verwaltungsberechtigung.

Request Body:

reason string Begründung der Ablehnung.

Idee als Spam markieren

POST /api/flowsaas/posts/{uuid}/spam

Markiert eine Idee als Spam. Anders als bei der Ablehnung wird niemand benachrichtigt. Verlangt die Verwaltungsberechtigung.

Für eine Idee stimmen

POST /api/flowsaas/posts/{uuid}/vote

Gibt eine Stimme im Namen des Benutzers des API-Schlüssels ab. Eine zweite Stimme derselben Person ist kein Fehler: added ist dann false und die Zahl bleibt unverändert.

Stimme zurückziehen

DELETE /api/flowsaas/posts/{uuid}/vote

Nimmt die Stimme des Benutzers des API-Schlüssels zurück. Lag keine vor, ist removed false.

Idee verbergen oder wieder zeigen

POST /api/flowsaas/posts/{uuid}/toggle-private

Kehrt die Sichtbarkeit für Portalbesucher um und meldet die Änderung an die Portal-Webhooks.

Idee als Duplikat zusammenführen

POST /api/flowsaas/posts/{uuid}/merge

Führt die Idee aus dem Pfad in die genannte Ziel-Idee desselben Portals über. Stimmen und öffentliche Kommentare wandern mit, interne Notizen bleiben beim Duplikat. Die Antwort zeigt die Ziel-Idee.

Request Body:

master_post_uuid string * Die Idee, die bestehen bleibt. Muss zum selben Portal gehören und eine andere sein.

Idee auf die Roadmap heben

POST /api/flowsaas/posts/{uuid}/promote-to-roadmap

Legt einen Roadmap-Eintrag für die Idee an und markiert sie entsprechend. Steht sie bereits auf der Roadmap, antwortet die Route mit HTTP 422 und error already_on_roadmap.

Ähnliche Ideen abrufen

GET /api/flowsaas/posts/{uuid}/similar

Bis zu zehn freigegebene, nicht abgeschlossene Ideen desselben Portals mit ähnlichem Wortlaut, die stimmstärksten zuerst. Die Idee selbst ist nicht dabei. Dieselbe Suche, die das Portal beim Schreiben anbietet.

💬 Kommentare

Intern oder öffentlich
Ein Kommentar mit is_internal true ist eine Teamnotiz und erreicht Portalbesucher nie. Ohne dieses Kennzeichen spricht der Kommentar im Namen des Unternehmens auf der Portalseite und löst die Portal-Webhooks aus.

Kommentare einer Idee auflisten

GET /api/flowsaas/posts/{uuid}/comments

Alle Kommentare der Idee, älteste zuerst, einschließlich der internen Notizen und der wartenden Beiträge.

Query-Parameter:

moderation_status string pending, approved, rejected oder spam.
is_internal boolean Nur interne Notizen beziehungsweise nur öffentliche Kommentare.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitenzahl, Standard 1.

Kommentar schreiben

POST /api/flowsaas/posts/{uuid}/comments

Schreibt einen Kommentar im Namen des Benutzers des API-Schlüssels. Er gilt sofort als freigegeben. Ein Bezugskommentar muss zu derselben Idee gehören, sonst antwortet die Route mit HTTP 422 und error parent_not_in_post.

Request Body:

body string * Der Text des Kommentars, höchstens 2000 Zeichen.
is_internal boolean true macht daraus eine Teamnotiz. Standard false, also öffentlich sichtbar.
parent_comment_uuid string Der Kommentar, auf den geantwortet wird. Muss zu dieser Idee gehören.

Auf einen Kommentar antworten

POST /api/flowsaas/comments/{uuid}/reply

Antwortet auf den Kommentar im Pfad. Die Idee ergibt sich aus diesem Kommentar, eine Antwort kann daher nie in einem fremden Strang landen.

Request Body:

body string * Der Text der Antwort, höchstens 2000 Zeichen.
is_internal boolean true macht daraus eine Teamnotiz.

Kommentar freigeben

POST /api/flowsaas/comments/{uuid}/approve

Gibt einen wartenden Kommentar für das Portal frei und benachrichtigt die verfassende Person. Verlangt die Verwaltungsberechtigung.

Kommentar ablehnen

POST /api/flowsaas/comments/{uuid}/reject

Lehnt einen Kommentar ab und benachrichtigt die verfassende Person. Verlangt die Verwaltungsberechtigung.

Kommentar als Spam markieren

POST /api/flowsaas/comments/{uuid}/spam

Markiert einen Kommentar als Spam, ohne jemanden zu benachrichtigen. Verlangt die Verwaltungsberechtigung.

Moderationszustand eines Kommentars setzen

PUT /api/flowsaas/comments/{uuid}/moderation

Setzt den Zustand ausdrücklich. Anders als die drei Kurzwege erreicht dieser Endpunkt auch pending und stellt einen Kommentar damit zurück in die Warteschlange. Verlangt die Verwaltungsberechtigung.

Request Body:

moderation_status string * pending, approved, rejected oder spam.

🗺️ Roadmap

Die Spalte ist der Status der Idee
Ein Roadmap-Eintrag hat keine eigene Spalte. Er steht dort, wo die Idee hinter ihm steht, weshalb das Verschieben eines Eintrags den Statuswechsel dieser Idee auslöst: mit Verlaufseintrag, Webhook und Benachrichtigung aller Unterstützer.
Einträge entstehen aus einer Idee
Ein Roadmap-Eintrag wird nicht hier angelegt, sondern über POST /api/flowsaas/posts/{uuid}/promote-to-roadmap. Ein Eintrag ohne Idee wäre ein Versprechen ohne Inhalt.

Roadmap-Einträge auflisten

GET /api/flowsaas/roadmap-items

Die Roadmap-Einträge aller Portale des Teams in ihrer veröffentlichten Reihenfolge.

Query-Parameter:

portal_uuid string Auf ein Portal einschränken.
status_uuid string Nur Einträge in dieser Spalte.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitenzahl, Standard 1.

Roadmap-Eintrag abrufen

GET /api/flowsaas/roadmap-items/{uuid}

Ein Roadmap-Eintrag mit Titel, Spalte und Stimmenzahl der Idee dahinter.

Position eines Roadmap-Eintrags ändern

PUT /api/flowsaas/roadmap-items/{uuid}

Ändert allein die Position innerhalb der bestehenden Spalte. Für einen Spaltenwechsel gibt es den Endpunkt move.

Request Body:

sort_order integer * Neue Position, ab 0.

Roadmap-Eintrag entfernen

DELETE /api/flowsaas/roadmap-items/{uuid}

Nimmt den Eintrag von der Roadmap. Die Idee bleibt mit Stimmen und Kommentaren bestehen und verliert nur ihre Roadmap-Markierung. Verlangt die Verwaltungsberechtigung.

Roadmap-Eintrag verschieben

POST /api/flowsaas/roadmap-items/{uuid}/move

Verschiebt den Eintrag in eine andere Spalte und an eine Position darin. Das ist ein Statuswechsel der Idee: er schreibt Verlauf, löst die Webhooks aus und benachrichtigt die Unterstützer. Die übrigen Einträge der Zielspalte werden neu durchnummeriert.

Request Body:

status_uuid string * Die Zielspalte, ein Status desselben Portals.
sort_order integer * Position in der Zielspalte, ab 0.

Für einen Roadmap-Eintrag stimmen

POST /api/flowsaas/roadmap-items/{uuid}/vote

Die Stimme landet auf der Idee hinter dem Eintrag, denn dort führt die Roadmap ihre Zahlen. Eine zweite Stimme derselben Person ist kein Fehler.

🔔 Webhooks

Der Schlüssel erscheint genau einmal
Die Antwort auf das Anlegen eines Webhooks trägt das Feld secret. Danach liefert keine Route ihn mehr aus. Wer ihn verliert, setzt über PUT einen neuen und hinterlegt ihn beim Empfänger.
Signatur der Zustellung
Jede Zustellung trägt X-FlowSaas-Signature (sha256=HMAC über Zeitstempel und Nutzlast), X-FlowSaas-Timestamp, X-FlowSaas-Event-ID und X-FlowSaas-Event-Type. Die Event-ID erkennt Wiederholungen. Weiterleitungen werden nie verfolgt, und die Zieladresse wird vor jeder Zustellung erneut geprüft.

Webhooks eines Portals auflisten

GET /api/flowsaas/portals/{uuid}/webhooks

Alle Webhooks des Portals, neueste zuerst, jeweils ohne Schlüssel.

Webhook anlegen

POST /api/flowsaas/portals/{uuid}/webhooks

Registriert einen Webhook auf dem Portal. Die Antwort enthält einmalig den Schlüssel für die Signaturprüfung. Verlangt die Verwaltungsberechtigung.

Request Body:

url string * Die Zieladresse der Zustellung.
events array * Mindestens eines aus post.created, post.status_changed, post.updated, comment.created, vote.created.
secret string Eigener Schlüssel, mindestens 16 Zeichen. Ohne Angabe wird einer erzeugt.
is_active boolean Ob sofort zugestellt wird. Standard true.

Webhook abrufen

GET /api/flowsaas/webhooks/{uuid}

Ein Webhook mit Zieladresse, abonnierten Ereignissen und Zeitpunkt der letzten erfolgreichen Zustellung. Der Schlüssel ist nicht dabei.

Webhook ändern

PUT /api/flowsaas/webhooks/{uuid}

Ändert die gesendeten Felder. Ohne secret bleibt der hinterlegte Schlüssel unverändert, damit ein Adresswechsel nicht die Signaturprüfung beim Empfänger bricht. Verlangt die Verwaltungsberechtigung.

Request Body:

url string Neue Zieladresse.
events array Die Ereignisse, die danach gelten sollen.
secret string Neuer Schlüssel, mindestens 16 Zeichen. Wird nicht zurückgegeben.
is_active boolean Zustellung ein- oder ausschalten.

Webhook löschen

DELETE /api/flowsaas/webhooks/{uuid}

Löscht den Webhook samt seinem Zustellungsprotokoll. Verlangt die Verwaltungsberechtigung.

Testzustellung senden

POST /api/flowsaas/webhooks/{uuid}/test

Sendet eine signierte Testnachricht an die hinterlegte Adresse und meldet das Ergebnis zurück. Ein Empfänger, der mit einem Fehler antwortet, ist ein erfolgreicher Aufruf mit erfolglosem Ergebnis: delivered ist dann false. Verlangt die Verwaltungsberechtigung.

Zustellungsprotokoll abrufen

GET /api/flowsaas/webhooks/{uuid}/logs

Die Zustellversuche des Webhooks, neueste zuerst, jeweils mit der gesendeten Nutzlast und der Antwort des Empfängers.

Query-Parameter:

event_type string Auf ein Ereignis einschränken, etwa post.created.
succeeded boolean Nur erfolgreiche beziehungsweise nur erfolglose Zustellungen.
per_page integer Einträge pro Seite, 1 bis 200, Standard 50.
page integer Seitenzahl, Standard 1.