Eigene Integration (Webhook)
Jeden Automatisierungslauf als signiertes Event an dein eigenes System senden - n8n, Make, Zapier oder eigener Code.
Zuletzt aktualisiert: 2026-11-07
fluss.ai führt die eingebauten Automatisierungen selbst aus — E-Mails, SMS, Bewertungen. Wenn du etwas brauchst, das wir nicht anbieten — ein CRM ohne native Anbindung, eine Benachrichtigung in deinen Kanal, ein eigenes Lead-Scoring — richtest du eine eigene Integration auf dein System ein. Wir schicken dir bei jedem Lauf ein signiertes Event.
Du betreibst die Logik. Wir speichern keine deiner Zugangsdaten.
Das funktioniert mit allem, was einen HTTP-POST empfangen kann: n8n, Make, Zapier, eine Lambda-Funktion oder dein eigenes Backend.
Einrichtung
- Lege eine Automatisierung vom Typ CRM-Integration an
- Wähle als Anbieter Eigener Webhook
- Trage deine Webhook-URL ein — dorthin senden wir den POST. Bei n8n ist das die Production URL des Webhook-Knotens, nicht der Link zum Workflow und nicht die Test-URL
- Klicke neben Signatur-Schlüssel auf Erzeugen und kopiere den Wert
- Klicke auf Testereignis senden, um die Zustellung zu prüfen
- Speichere und hänge die Automatisierung an deinen Flow
Kopiere den Signatur-Schlüssel sofort. Wir speichern ihn verschlüsselt und zeigen ihn danach nicht mehr an. Geht er verloren, erzeugst du einen neuen und hinterlegst ihn an beiden Stellen.
Der Schlüssel ist das, womit dein Endpunkt beweisen kann, dass eine Anfrage wirklich von fluss.ai kommt. Ohne ihn kann jeder, der deine URL kennt, gefälschte Leads in dein CRM schreiben.
Weitere Felder
| Feld | Bedeutung |
|---|---|
| Authorization-Token | Optional. Wird als Bearer-Token gesendet, falls dein Endpunkt eine eigene Authentifizierung verlangt. |
| Template-Variablen mitsenden | Fügt die vollständige Variablen-Map hinzu. Größere Requests, meist nicht nötig. |
Das Event
POST an deine URL, Content-Type: application/json.
Header
| Header | Bedeutung |
|---|---|
x-fluss-signature | t=<Unix-Sekunden>,v1=<hex hmac> — siehe unten |
x-fluss-timestamp | Derselbe Zeitstempel, der Bequemlichkeit halber |
x-fluss-event | Name des Ereignisses, aktuell immer lead.automation |
x-fluss-delivery | Eindeutige ID dieser Zustellung — damit kannst du Duplikate erkennen |
Authorization | Bearer <dein Token>, nur wenn du einen hinterlegt hast |
Body
{
"version": 1,
"event": "lead.automation",
"executionId": 84213,
"attempt": 1,
"account": { "userId": "user_2ab…", "orgId": null },
"lead": {
"hashId": "K9mQx2",
"locale": "de",
"firstName": "Ada",
"lastName": "Lovelace",
"salutation": "ms",
"email": "ada@example.com",
"phone": "+4915112345678",
"street": "Unter den Linden",
"streetNumber": "1",
"postalCode": "10117",
"city": "Berlin",
"country": "DE",
"latitude": "52.5170",
"longitude": "13.3889",
"segment": "WHG_K",
"spaceLiving": 84,
"spacePlot": null,
"yearOfConstruction": 1998,
"propRooms": 3,
"value": 512000,
"rentMonthly": 1706,
"currency": "EUR",
"valuationUrl": "https://fluss.ai/f/…",
"status": "new",
"source": "website",
"createdAt": "2026-08-18T09:14:22.000Z"
},
"template": { "id": 12, "name": "An mein CRM senden" }
}
hashId ist die öffentliche ID des Leads — damit rufst du uns zurück.
value ist null, wenn die Immobilie nicht automatisch bewertet werden
konnte — ein ungewöhnliches Segment oder eine Adresse außerhalb der
Abdeckung. Das ist normal, fang den Fall ab.
Stabilität
version wird nur bei einer Breaking Change erhöht. Neue Felder können jederzeit dazukommen — lies tolerant und ignoriere, was du nicht kennst.
Signatur prüfen
Bilde HMAC-SHA256 über <timestamp>.<roher Body> mit deinem Signatur-Schlüssel und vergleiche das Ergebnis mit v1 aus dem Header.
Signiere die rohen Bytes des Body, genau wie empfangen. Wer geparstes JSON neu serialisiert, ändert womöglich die Reihenfolge der Schlüssel — dann passt die Signatur nicht mehr.
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(',').map((p) => {
const [k, ...rest] = p.trim().split('=');
return [k, rest.join('=')];
})
);
const timestamp = Number(parts.t);
if (!Number.isFinite(timestamp)) return false;
// Replays abweisen. 5 Minuten sind unsere Empfehlung.
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(parts.v1 ?? '', 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Zustellung
- Timeout 20 Sekunden. Antworte schnell und erledige Langsames asynchron.
- Wiederholungen bei
5xx,429und Netzwerkfehlern: 1 Min → 5 Min → 25 Min, insgesamt vier Versuche.4xxgilt als endgültig und wird nicht wiederholt. - Weiterleitungen werden nicht verfolgt. Trage direkt die Ziel-URL ein.
- Private Adressen werden abgelehnt. Wir rufen kein Loopback, keine internen Netze und keine Cloud-Metadaten-Adressen auf. Dein Endpunkt muss aus dem Internet erreichbar sein.
- Mindestens einmal. Nach einem Timeout kann eine Wiederholung etwas zustellen, das du schon verarbeitet hast. Dedupliziere über
x-fluss-deliveryoderexecutionId.
Jeder Versuch ist in fluss.ai in der Timeline des Leads sichtbar, mit Status und einem Ausschnitt der Antwort.
Testen
Testereignis senden stellt sofort einen Beispiel-Lead an deine URL zu, signiert wie ein echtes Ereignis. In deinem Konto wird nichts gespeichert.
Der Body hat dieselbe Form wie ein echter, mit zusätzlichem test: true und offensichtlich erfundenen Daten (Ada Lovelace, eine example.com-Adresse).
Nutze das Flag, um keinen Testkontakt in dein echtes CRM zu schreiben — aber baue keinen anderen Code-Pfad darauf. Sonst sagt ein bestandener Test nichts über das echte Ereignis aus.
Die Fehlermeldung kommt direkt vom Zustellversuch: eine falsche URL, ein ungültiges TLS-Zertifikat oder eine abgelehnte private Adresse stehen genau so da.
Zurück nach fluss.ai schreiben
Lege unter Konto → API-Schlüssel einen Schlüssel an und wähle nur die Berechtigungen, die du brauchst. API-Schlüssel setzen ein Pro-Paket voraus. Er wird einmal angezeigt — sichere ihn sofort. Der Schlüssel gilt nur für dein Konto und lässt sich jederzeit widerrufen.
Sende ihn als x-fluss-api-key: flk_… oder als Authorization: Bearer flk_….
| Endpunkt | Berechtigung | Zweck |
|---|---|---|
external.getLead | leads:read | Den vollständigen Lead abrufen |
external.updateLead | leads:write | Felder anreichern oder korrigieren |
external.addComment | comments:write | Notiz in der Timeline des Leads |
external.attachDocument | documents:write | Datei am Lead ablegen |
external.createLead | leads:create | Lead aus eigenem Formular anlegen |
external.whoami | leads:read | Schlüssel und Berechtigungen prüfen |
curl https://fluss.ai/api/trpc/external.addComment \
-H "x-fluss-api-key: $FLUSS_API_KEY" \
-H "x-raw-output: 1" \
-H "content-type: application/json" \
-d '{"json":{"leadHashId":"K9mQx2","text":"In HubSpot angelegt als #4711"}}'
x-raw-output: 1 liefert einfaches JSON statt unseres internen Formats.
updateLead nimmt Kontaktdaten, Adresse, value, rentMonthly, status, priority, source und valuationUrl. Weggelassene Felder bleiben unangetastet, eine Teil-Aktualisierung löscht also nichts.
Leads aus deinem eigenen Formular anlegen
Wenn du die Angaben selbst einsammelst, mit einem Formular auf deiner Website oder aus deinem CRM, schick sie an external.createLead. fluss.ai legt den Lead im angegebenen Funnel an und führt dessen Automatisierungen aus, genau so, als hätte der Eigentümer den Funnel ausgefüllt: Die Bewertung wird erstellt und verschickt, Follow-ups werden geplant, die CRM-Übertragung läuft.
Du brauchst dafür einen Schlüssel mit der Berechtigung leads:create und das Pro-Paket.
curl https://fluss.ai/api/trpc/external.createLead \
-H "x-fluss-api-key: $FLUSS_API_KEY" \
-H "x-raw-output: 1" \
-H "content-type: application/json" \
-d '{"json":{
"funnelId": "Xk3pQ",
"contact": { "salutation": "mr", "firstName": "Max", "lastName": "Mustermann",
"email": "max@example.com", "phone": "+49 151 2345678" },
"address": { "street": "Hauptstraße", "streetNumber": "5",
"postalCode": "82205", "city": "Gilching" },
"property": { "segment": "EZFH_K", "spaceLiving": 140, "spacePlot": 520,
"yearOfConstruction": 1998, "qualityFurnishings": 2 },
"consent": true,
"source": "website-formular"
}}'
{
"leadId": "K9mQx2",
"duplicate": false,
"link": "https://fluss.ai/leads/K9mQx2",
"automations": "started",
"limits": {
"today": {
"used": 1,
"limit": 20,
"resetsAt": "2026-11-07T23:00:00.000Z"
},
"thisMonth": {
"used": 1,
"limit": 100,
"resetsAt": "2026-11-30T23:00:00.000Z"
}
}
}
funnelIdist die ID in der Adresse des Funnel-Editors,fluss.ai/flow-groups/<id>.consentmusstruesein. Damit bestätigst du, dass der Eigentümer der Kontaktaufnahme und der Verarbeitung seiner Daten zugestimmt hat. Diese Einwilligung in deinem Formular einzuholen, liegt bei dir.contactbraucht eine E-Mail-Adresse oder eine Telefonnummer.automationsiststarted,paused(die Automatisierungen des Funnels sind ausgeschaltet),none(der Funnel hat keine),not-run(ein Duplikat, siehe unten) oderfailed(der Lead ist gespeichert, seine Automatisierungen ließen sich aber nicht starten; wir werden benachrichtigt, schick ihn also nicht noch einmal).
Unbekannte Feldnamen werden mit dem Namen des Felds abgelehnt. Ein Tippfehler kostet einen Lead also nicht unbemerkt seine Bewertung.
Was eine Bewertung braucht
Bei einem Funnel, der eine Bewertung verschickt, sind die Adresse (street, postalCode, city) und die Immobilienart immer Pflicht, dazu:
segment | Immobilie | Außerdem Pflicht |
|---|---|---|
WHG_K | Wohnung | spaceLiving, yearOfConstruction, qualityFurnishings |
EZFH_K | Haus | spaceLiving, spacePlot, yearOfConstruction, qualityFurnishings |
MFHWGH_K | Mehrfamilienhaus / Gewerbe | spaceLiving, spacePlot, yearOfConstruction |
GRST_K | Grundstück | spacePlot |
Die Tabelle gilt für Immobilien in Deutschland. Für andere Länder setzt du country (z. B. AT), dann sind nur Adresse und Immobilienart Pflicht. Schick streetNumber mit, wann immer du sie hast: Mit Hausnummer wird die Bewertung genauer.
Flächen sind in m². Drei Felder nehmen eine Zahl auf einer Skala von 0 bis 4. Der Funnel fragt sie mit wenigen Antworten ab, und wenn du dieselben Zahlen schickst, bekommst du dieselbe Bewertung wie ein Lead aus dem Funnel:
| Feld | Antwort im Funnel → Wert |
|---|---|
qualityFurnishings | Einfach 0, Normal 2, Gehoben 4 |
propertyCondition | Schlecht 0, Normal 2, Sehr gut 4 |
degreeModernizationCategory | Unsaniert oder nicht bekannt 0, Geringfügig 1, Mittelmäßig 2, Umfassend saniert 3 |
Die Werte dazwischen (und 4 bei der Modernisierung) gehen auch, wenn dein Formular feiner fragt.
Optional, und genutzt, wenn vorhanden: yearOfModernization, propRooms, buildingType (Häuser: 7 freistehend, 8 Reihenmittelhaus, 9 Reihenendhaus oder Doppelhaushälfte, 10 Zweifamilienhaus, 33 unbestimmt), apartmentType, buildingFloor, buildingFloors, buildingUnits, spaceCommercial, propEnergy und die Ja/Nein-Felder propCellar, propElevator, propGarage, propGarageUnderground, propParkingLot, propBalconyTerrace, propAdditionalBathroom, propRented.
Fehlt etwas, das die Bewertung braucht, schlägt der Aufruf mit einer Liste der fehlenden Felder fehl und es wird nichts gespeichert. Du kannst ihn also korrigieren und einfach noch einmal schicken.
Grenzen
- 20 Leads am Tag und 100 im Monat pro Konto, API und KI-Assistent zusammengezählt. Tage und Monate richten sich nach deutscher Zeit. Jede Antwort zeigt, wie viel verbraucht ist und wann es zurückgesetzt wird. Du brauchst mehr? Schreib an support@fluss.ai.
- Dieselbe Person mit derselben Immobilie innerhalb von 30 Tagen liefert den bestehenden Lead mit
duplicate: truezurück. Es läuft nichts noch einmal, und es zählt nicht. Die Person ist die E-Mail-Adresse, ohne E-Mail die Telefonnummer; die Immobilie sind Straße, Hausnummer, PLZ und Immobilienart. - Über einer Grenze schlägt der Aufruf mit
429fehl und es wird nichts gespeichert. Schick ihn nachresetsAtnoch einmal.
Fehler
| Status | Bedeutung |
|---|---|
400 | Die Eingabe ist ungültig, die Meldung nennt das Feld |
401 | Der Schlüssel fehlt oder ist ungültig |
403 | Dem Schlüssel fehlt leads:create, oder das Konto hat kein Pro-Paket |
404 | In deinem Konto gibt es keinen Funnel mit dieser ID |
412 | Der Funnel nutzt noch ältere Automatisierungen, die wir erst umstellen müssen. Schreib an support@fluss.ai |
422 | Für die Bewertung fehlen Felder (in der Meldung aufgelistet) |
429 | Tages- oder Monatsgrenze erreicht |
Startvorlage für n8n
Lade fluss-lead-starter.n8n.json herunter und importiere die Datei in dein eigenes n8n (Workflows → Import from File).
Sie kommt fertig verdrahtet: Webhook-Trigger → Signaturprüfung → Feld-Zuordnung → Platzhalter für dein CRM → Notiz zurück nach fluss.ai.
Danach:
- Kopiere die Production-URL aus dem Knoten Fluss Webhook nach fluss.ai
- Setze
FLUSS_WEBHOOK_SECRETin deinem n8n auf den Signatur-Schlüssel - Setze
FLUSS_API_KEY, wenn du den Rückschreib-Knoten nutzen willst - Ersetze den Knoten Your CRM durch dein echtes CRM
Das läuft auf n8n Cloud genauso wie selbst gehostet — es ist in beiden Fällen deine Instanz.
Umstieg von unserem n8n
Kunden, die eigene Automatisierungen wollten, bekamen früher einen Account auf unserem n8n, und wir haben den Workflow gebaut und gepflegt. Das läuft aus: fluss.ai führt seine Automatisierungen jetzt selbst aus.
| Vorher | Jetzt |
|---|---|
| Dein Workflow lag auf unserem n8n | Er liegt auf deinem n8n (oder Make, Zapier …) |
| Wir haben ihn betrieben | Du betreibst ihn — und kannst ihn jederzeit ändern |
| Rückschreiben mit einem Admin-Token von uns | Rückschreiben mit deinem eigenen API-Schlüssel |
| Unser Support hat ihn gebaut | Startvorlage importieren — oder uns weiter fragen |
Der eigene API-Schlüssel ist der eigentliche Gewinn: das alte Token war weit mächtiger, als eine Integration je braucht. Deiner gilt nur für dein Konto und nur für die Berechtigungen, die du auswählst.
Voraussetzungen
- fluss.ai Pro oder höher (CRM-Integrationen sind ab dem Pro-Paket verfügbar)
- Ein aus dem Internet erreichbarer HTTPS-Endpunkt
Wenn du lieber möchtest, dass wir es bauen: der Kontaktlink steht direkt auf der Integrationsseite. Oder schreib uns an support@fluss.ai.