Zum Hauptinhalt springen

Webhook API

Mit der Webhook-API von Heyflow kannst Du jede Eingabe direkt an einen beliebigen URL-Endpunkt senden, sobald sie abgeschickt wurde.

Heyflow avatar
Verfasst von Heyflow
Diese Woche aktualisiert

⭐ Verfügbar in den folgenden Plänen: Pro & Agency (limitiert), Business

👀 Nicht sicher, welchen Plan du hast? Überprüfe dein Abonnement.

Ein Webhook ist eine Möglichkeit für deinen Heyflow, Informationen sofort an einen anderen Dienst oder eine andere Anwendung zu senden, wenn jemand eine Antwort einreicht. Stelle dir das wie eine automatische Nachricht vor, die ein anderes System über die neue Übermittlung benachrichtigt, so dass du die Daten in Echtzeit verarbeiten kannst. Heyflow ermöglicht die Erstellung benutzerdefinierter Webhooks, die jede Übermittlung direkt an einen beliebigen URL-Endpunkt senden, der die Antwortdaten im JSON-Format empfängt.

Im Business-Plan gibt es zahlreiche Anpassungsmöglichkeiten, um den Webhook an deine Anforderungen anzupassen.

Dieser Artikel enthält:


Einen neuen Webhook einrichten

  1. Gehe zum Tab Integrieren und dann auf Hooks.

  2. Nachdem du eine gültige URL angegeben hast, kannst du zur besseren Identifizierung einen Namen für den Webhook festlegen.

  3. Wenn du auf Testen klickst, wird ein Beispieltext mit folgendem Format an die URL gesendet.

Testen der Webhook-Payload:

{
flowID: <YourFlowID>,
id: 'demo-response-id', // Heyflow UUID for the response
createdAt: new Date(), // datetime of the test trigger,
fields: {
'Demo Field 1': 'Some value', // 'Demo Field 1' is your system label,
'Demo Field 2': 'Some other value',
},
}

Nach einem erfolgreichen Test (HTTP-Statuscode 200) aktiviere deinen Webhook. Von nun an wird jede neue Anmeldung an die angegebene URL gesendet.


Anpassen deines Webhooks (Business Plan)

Wenn du den Business Plan nutzt, hast du zusätzliche Optionen, um deinen Webhook anzupassen.

  • HTTP-Methoden: Wähle, wie die Daten gesendet werden sollen (POST, PUT oder GET).

  • Benutzerdefinierte Kopfzeilen: Füge spezifische Informationen hinzu, die das empfangende System benötigt.

  • URL-Parameter: Füge feste Details wie API-Schlüssel in die Webhook-URL ein.

  • Grundlegende Authentifizierung: Sichere deinen Webhook mit einem Benutzernamen und einem Passwort.

  • Erweiterte Nutzdaten: Erhalte detailliertere Informationen über jede Übermittlung.

Einfache Webhook-Payload

Dies ist das Standardformat, das mit jedem Absenden des Flows übermittelt wird:

{
flowID: <YourFlowID>,
id: <HeyflowResponseUUID>, // Heyflow UUID for the response
createdAt: <DateTimeOfTheResponseSubmission>, // new Date()
fields: {
"System Label": "Value"
},
}

Achtung: Wenn du möchtest, dass die Download-Links vollständige Datei-URLs sind, von denen du die Dateien programmgesteuert herunterladen kannst, musst du den Zugriff auf öffentliche Links in deinen Flow-Einstellungen aktivieren.

Erweiterte Webhook-Payload (Business Plan)

Wenn du den Business Plan abonniert hast, kannst du auch eine erweiterte Payload senden. Dieses Format ist nützlich, wenn du einen detaillierten Kontext zu jedem Feld benötigen. Vor allem aber ändert sich der Typ der Felder von einem Objekt zu einem Array von Objekten.

{
flowID: <YourFlowID>,
id: <HeyflowResponseUUID>, // Heyflow UUID for the response
createdAt: <DateTimeOfTheResponseSubmission>, // new Date()
fields: [
{
// Each block has a static unique identifier, the ID:
"id": "mco-fb5cd9b5",
// The label is either the system label or block label you define:
"label": "Please choose an option",
// The values holds the user entered data in an array. If only one
// value can be specified, e.g. an input field, it only holds one
// object. If mutliple values can be speificed, e.g. for a Multiple
// Choice block, it holds multiple elements.
"values": [
{
"name": "mco-fb5cd9b5",
"answer": "Option 2 label"
}
],
// The variable you have specified for this block.
"variable": "mc-24115746",
// If this block is flagged as senstivive as a boolean.
"sensitive": false,
},
],
}

❗Bitte beachte: Die Struktur und der Inhalt der erweiterten Nutzlast sind von Heyflow vordefiniert und können nicht angepasst werden. Du kannst zusätzliche Informationen einfügen, indem du versteckte Eingabefelder in deinem Flow hinzufügst. Diese Felder können zusätzliche Daten erfassen (z. B. Tracking-Parameter, User-Metadaten) und werden bei der Übermittlung in die Nutzdaten aufgenommen.


Hinzufügen von (festen) URL Parametern

Du kannst feste Parameter an deine Webhook-URL anhängen.

Beispiel:

  • Ursprüngliche URL: https://www.example.com/webhookparty

  • Mit URL-Parametern: https://www.example.com/webhookparty?clientID=12345&apiKey=abcdef

❗Bitte beachte: Dynamische Daten aus User-Eingaben oder Flow-Variablen können nicht in URL-Parametern verwendet werden.


URL Parameter Tracking

Wenn du URL/UTM-Parameter aus deinem Flow an den Webhook weitergeben möchtest, musst du ein verstecktes Eingabefeld einrichten, um die Daten zu erfassen. Sobald das Feld eingerichtet ist, kannst du es mit den entsprechenden Feldern in deiner bevorzugten Antwort-Routine verknüpfen.

Die UTM-Parameter werden dann automatisch mit jeder Antwort übermittelt – und das, ohne dass deine Besucher es bemerken. 🚀


Error Status Codes

Sobald wir ein Problem mit deiner Webhookintegration feststellen, senden wir dir eine E-Mail mit der Flow ID sowie dem Error Status Code (HTTP-Statuscode), wie z.B.

Error: Request failed with status code 503.

In diesem Beispiel erhältst du den Fehler, weil der Server nicht erreichbar ist und temporär nicht zur Verfügung steht.

Diese Fehlercodes erhalten wir von den URLs bzw. Servern, die du in der Integration nutzt. Wir leiten den Fehler also nur weiter.

🔎 Für eine Übersicht der Error Codes schaue hier vorbei.

Hat dies deine Frage beantwortet?