Werkzeuge

Assistenten
Parameter
Seriendruckvorlagen
Webhooks
Datenbank
Systemvorlagen

Eingehende Webhooks

Eingehende Webhooks ermöglichen es, Syncler aus externen Systemen heraus anzusprechen – zum Lesen, Schreiben oder zum Starten von Syncs (Ad-hoc). Sie definieren dafür Endpunkte, Schemata (Request/Response) und optional Sicherheits- sowie Steuerungsparameter. So lassen sich Integrationen leicht anschließen, ohne dass Drittsysteme die komplette Syncler-API kennen müssen.

Funktionsumfang auf einen Blick

  • Aufrufe per GET (URL-Parameter) oder POST (JSON-Body oder Form-Daten).
  • Request-/Response-Schemata (JSON) zur strukturierten Übergabe und Validierung.
  • Datenoperationen: Lesen/Schreiben über Sync (mit Transformation & Mapping) oder direkt über System (Schema-basiert).
  • Ad-hoc-Ausführung: Startet Syncs/Abläufe mit übergebenen Kontextdaten.
  • Sicherheit: Webhook-ID, optionales Secret im Header, aktiv/inaktiv-Schaltung.
  • Bedingungen & Platzhalter: Formelbasiertes Gatekeeping, dynamische Filter, Paging.

Aufrufvarianten

  • GET
    Querystring-Parameter werden als Quelldaten interpretiert.

  • POST (JSON)
    Erwartet ein JSON-Objekt im Request-Body.

  • POST (Form-Data / x-www-form-urlencoded)
    Formularfelder werden serverseitig zu einem JSON-Objekt konvertiert
    (Feldnamen → Propertynamen).

Hinweis: Die Webhook-ID für die URL wird automatisch generiert und in der Maske angezeigt. Die vollständige URL ergibt sich aus API-Basis-URL + Webhook-ID.

Sicherheit

  • Aktiv-Schalter
    Nur aktive Webhooks sind aufrufbar. Inaktive Endpunkte antworten mit 410 Gone.

  • Optionales Secret
    Übergabe im Header syncler_webhooksecret oder Authorization.
    Ist kein Secret hinterlegt, entfällt die Prüfung.

  • LinkedIn-Validierung (optional)
    Für LinkedIn-Registrierungen kann ein ClientSecret hinterlegt werden. Die Validierung nutzt HMAC-SHA256 über den Challenge-Code. (Details siehe LinkedIn-Dokumentation.)

Bedingungen & Platzhalter

  • Ausführungsbedingung
    Formel, die mit Platzhaltern aus den Anfragedaten (in #…#) befüllt wird.
    Liefert die Bedingung false, wird die Aktion nicht ausgeführt.

  • Typische Platzhalter

    • #Feldname# – Wert aus der eingehenden Anfrage
    • #FlowFilter# – wird in Abfragen ersetzt (siehe „Lesen von Abfragen“)

Beispiel (Bedingung): #eventType# = 'created' AND #source# <> ''

Einstellungen

1) Allgemein

  • Name
    Administrative Bezeichnung.

  • Ist aktiv
    Schaltet die Erreichbarkeit des Endpunkts.

2) Empfänger

  • Geheimnis (Secret)
    Optionales Secret zur Header-Validierung (syncler_webhooksecret / Authorization).

  • Ausführungsbedingung
    Formel (true/false) mit Platzhaltern aus den Requestdaten.

  • Empfangene Daten im Protokoll speichern
    Speichert den Requestpayload zusammen mit dem Protokolleintrag (erhöht DB-Last).

  • LinkedIn ClientSecret
    Für die Challenge-Response-Validierung bei LinkedIn-Webhook-Registrierung.

  • Webhook / Webhook-URL / LinkedIn-URL
    Schreibgeschützte IDs/URLs (werden aus Basis-URL + ID gebildet).

3) Verarbeitung

  • Aktion ausführen
    Legt fest, was passieren soll (siehe Abschnitt „Aktionen“).

  • Sync für Aktion
    Der zu verwendende Sync (z. B. für Lesen/Schreiben/Starten).
    Für Lesen/Schreiben per Sync sind Webhook-Sync-Typen erforderlich.

  • System für Aktion
    Direktes Lesen/Schreiben ohne Sync – erfordert Schemaobjekte im System.

  • Schema-Objekt für System
    Das Ziel-/Quellschema in der Systemverbindung.

  • Weiterleitungs-URL nach dem Ausführen
    Optionaler Redirect (z. B. nach Formularübermittlung).

  • Daten im Datensatz-Speicher für diesen Sync ablegen
    Übergibt die eingehenden Daten in den Datensatz-Speicher des gewählten Syncs.
    → Nutzen Sie in Abläufen den Typ: „Universal Ablauf – Daten aus Datensatz-Speicher lesen“.
    Bei Aktivierung erhält der Ad-hoc-Start nur die GUID des gespeicherten Datensatzes (nicht die Daten selbst).

4) Lesen von Daten

  • Suche nach Quelldatensatz für Sync oder System
    WHERE-Klausel mit Platzhaltern (SQL/OData – abhängig vom Zielsystem).

  • Sortierung
    Order-By-Klausel (falls unterstützt).

  • Nur den ersten Datensatz zurückgeben
    Antwort als einzelnes JSON-Objekt statt Array. Hier sollte die Sortierung verwendet werden.

5) Lesen von Abfragen

  • Abfrage-Filter für Lesen einer Abfrage
    Ersetzt den Platzhalter #FlowFilter# in der Abfrage (Sync oder System-Abfrage).

  • Ergebnis in Seiten liefern
    Liefert ein Objekt { data, total } (nur „Lese Abfrage mit System“).

  • Name aus Anfrage für Seitengröße
    Default: pageSize.

  • Name aus Anfrage für ersten Datensatz
    Default: offset (0-basiert).

6) Schreiben von Daten

  • Suche nach Zieldatensatz für System
    WHERE-Klausel zur Identifikation des zu aktualisierenden Datensatzes mit Platzhaltern.

  • Verhalten bei keiner Übereinstimmung (System-Schreiben)
    Überspringen oder Neu anlegen.

  • Verhalten bei exakter Übereinstimmung (System-Schreiben)
    Überspringen oder Aktualisieren.

Zusätzliche Registerkarten

  • JSON-Schema Anfrage
    Schema für Requestdaten (POST-JSON, Query-Parameter, Form-Felder).
    Kann entfallen, wenn die Verarbeitung ausschließlich über Sync erfolgt.

  • JSON-Schema Antwort
    Schema für die Antwort (Objekt/Array/Paging-Objekt).
    Wird beim direkten Lesen über System benötigt; beim Sync-Weg liegt das Antwortschema am Sync.

  • Zuordnungen Lesen / Zuordnungen Schreiben
    Mapping zwischen System-Schema und Webhook-(Antwort/Anfrage)-Schema für System-basierte Aktionen.

  • Zuordnungen Lesen bei Schreibaktionen Optional: Direktes Zurücksenden des gespeicherten Datensatzes (z. B. zur Rückgabe einer generierten ID).

Aktionen

Starte Sync

Erzeugt einen Ad-hoc-Warteschlangen-Eintrag für den gewählten Sync.

  • Eingangsdaten werden als Ausführungsparameter mitgegeben (oder als GUID, wenn Datensatz-Speicher aktiv ist).
  • Die Ausführung erfolgt durch den Daemon.

Lese Daten mit Sync

  • Erfordert einen Webhook Sync zum Lesen.
  • WHERE/ORDER werden aus den Webhook-Einstellungen + Platzhaltern gebildet.
  • Transformation & Zuweisungen des Syncs werden angewendet.
  • Antwort: JSON-Array (oder erstes Objekt, falls konfiguriert).

Lese Abfrage mit Sync

  • Erfordert einen Webhook Sync zum Lesen einer Abfrage.
  • #FlowFilter# wird aus dem Webhook-Filter ersetzt.
  • Antwort: JSON-Array (oder erstes Objekt).

Speichere Daten mit Sync

  • Erfordert einen Webhook Sync zum Schreiben.
  • Transformation, Zuweisungen, Vorbedingung & Übereinstimmungssuche werden im Sync definiert.
  • Antwort: Status/Ergebnis gemäß Sync-Konfiguration.

Lese Daten mit System

  • Direktes Lesen über System (Schema-basiert).
  • Erfordert Suche, Antwort-Schema und Lesemapping am Webhook.
  • Keine Transformation möglich.

Lese Abfrage mit System

  • Führt eine System-Abfrage aus (Konfiguration im Bereich „Abfrage“).
  • Antwort über Lesemapping ins Webhook-Antwortschema.
  • Optional Paging { data, total }.
  • Keine Transformation möglich.

Speichere Daten mit System

  • Schreibt direkt über System (Schema-basiert).
  • Zielschema auswählen und Schreibmapping definieren.
  • Optional: Suche + Verhalten bei (Nicht-)Treffer.
  • Keine Transformation möglich.

Abläufe starten

Abläufe haben keine direkte Datensatzverarbeitung. Für „Starte Sync“ in einem Ablauf:

  1. Eingehende Daten per Webhook in den Datensatz-Speicher eines Lese-Syncs schreiben
    (Typ: „Universal Ablauf – Daten aus Datensatz-Speicher lesen“).
  2. Den Lese-Sync als ersten Schritt in den Ablauf einfügen.
  3. Nach erfolgreicher Verarbeitung löscht der Ablauf die verwendeten Speicher-Datensätze.

So lassen sich mehrere nachgelagerte Syncs gekettet ausführen.

Formulare (Web-Form)

  • Content-Type wird automatisch erkannt (JSON vs. Form-Daten).
  • Formularfelder → JSON-Objekt (Feldname = Propertyname).
  • Weiterleitungs-URL am Webhook hinterlegen (z. B. Landingpage).
  • Ablauf: Formular → Webhook → Verarbeitung → Redirect.

Beispiele

GET mit Secret

GET /api/webhooks/{webhookId}?eventType=created&source=web
Host: <api-host>
syncler_webhooksecret: <secret-value>

POST (JSON) – Start Sync

POST /api/webhooks/{webhookId}
Content-Type: application/json
Authorization: <secret-or-bearer>

{
  "source": "leadform",
  "email": "me@example.com",
  "firstName": "Mia",
  "lastName": "Muster",
  "consent": true
}

Paging-Parameter (bei „Lese Abfrage mit System“)

{
  "pageSize": 50,
  "offset": 0,
  "filter": "status='open'"
}

Webhook testen

Mit der integrierten Test-Funktion können Sie einen Webhook direkt aus der Oberfläche aufrufen – ohne externe Tools. Der Test führt keine Simulation aus, sondern triggert alle konfigurierten Aktionen real (Lesen/Schreiben/Sync-Start). Verwenden Sie daher geeignete Testdaten und/oder eine Testumgebung.

In Kombination mit einem Pin auf einen Protokolleintrag des Webhooks inklusive Empfangsdaten kann damit auch eine Wiederholung ausgeführt werden.

Voraussetzungen

  • Ein aktiver Webhook (Schalter Ist aktiv eingeschaltet).
  • Bei Sync- oder System-Aktionen: die jeweilige Konfiguration (Schema, Zuordnungen, Filter, Abfrage, etc.) ist vollständig.

Aufruf der Test-Funktion

  1. Öffnen Sie den Webhook in der Oberfläche.
  2. Klicken Sie auf Aktionsmenü → Testen.
  3. Der Testdialog öffnet sich mit drei Bereichen:
    • Daten senden (Pin/JSON-Editor)
    • Empfangene Daten (Server-Antwort)
    • Nachrichten-Ticker (Live-Meldungen)

Testdaten festlegen (Bereich Daten senden)

Sie haben zwei komfortable Wege, die eingehenden Daten zu definieren:

  • Per Pin
    Wählen Sie einen vorhandenen Pin aus. Der gespeicherte Datensatz wird als Requestpayload verwendet.

  • Per manueller JSON-Eingabe
    Geben Sie Ihren Request-Body im JSON-Editor ein (z. B. Formulardaten, Event-Payload).

Aufruf ausführen

  • Klicken Sie auf die Pfeil-Schaltfläche (rechts), um den Test sofort auszuführen.
  • Der Aufruf geht an die echte Webhook-URL (keine Simulation).
  • Je nach Aktion können Schreiboperationen, Sync-Starts oder Systemabfragen erfolgen.

Ergebnisse prüfen

1) Empfangene Daten (Response)

  • Zeigt den Rohinhalt der Webhook-Antwort (JSON-Objekt, JSON-Array oder Paging-Objekt { data, total }, je nach Aktion).
  • Zusätzlich wird der HTTP-Statuscode angezeigt, z. B.:
    • 200 OK – Erfolg mit Antwortinhalt
    • 204 No Content – Erfolg ohne Ergebnis (z. B. kein Datensatz gefunden, erstes Objekt angefordert)
    • 403 – Secret/Autorisierung fehlt oder ist ungültig
    • 410 Gone – Webhook ist inaktiv

2) Nachrichten-Ticker

  • Zeigt laufende Statusmeldungen (z. B. Start, Filter, Treffer, gespeicherte Datensätze, Warnungen/Fehler).
  • Nützlich für Schritt-für-Schritt-Diagnosen (insb. bei Transformationen oder Abfragen).

Webhook testen