Eigene Integration (Webhook)

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

1. Lege eine Automatisierung vom Typ CRM-Integration an
2. Wähle als Anbieter Eigener Webhook
3. Trage deine Webhook-URL ein — dorthin senden wir den POST
4. Klicke neben Signatur-Schlüssel auf Erzeugen und kopiere den Wert
5. Klicke auf Testereignis senden, um die Zustellung zu prüfen
6. Speichere und hänge die Automatisierung an deinen Flow

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

Das Event

POST an deine URL, Content-Type: application/json.

Header

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.

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.

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, 429 und Netzwerkfehlern: 1 Min → 5 Min → 25 Min, insgesamt vier Versuche. 4xx gilt 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-delivery oder executionId.

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

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_….

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.

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:

1. Kopiere die Production-URL aus dem Knoten Fluss Webhook nach fluss.ai
2. Setze FLUSS_WEBHOOK_SECRET in deinem n8n auf den Signatur-Schlüssel
3. Setze FLUSS_API_KEY, wenn du den Rückschreib-Knoten nutzen willst
4. 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.

Voraussetzungen

• fluss.ai Pro oder höher (CRM-Integrationen sind ab dem Pro-Paket verfügbar)
• Ein aus dem Internet erreichbarer HTTPS-Endpunkt