Webhooks werden in der Regel für den Austausch von Informationen zwischen verschiedenen Anwendungen verwendet. Heyflow ermöglicht es, benutzerdefinierte Webhooks zu erstellen, die bei jeder Absenden-Aktion direkt an einen beliebigen URL-Endpunkt senden, der die gesamten Antwortdaten 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
Gehe zum Tab Integrieren und dann auf Hooks.
Nachdem du eine gültige URL angegeben hast, kannst du zur besseren Identifizierung einen Namen für den Webhook festlegen.
Wenn du auf Testen klickst, wird ein Beispieltext mit folgendem Format an die URL gesendet. Bitte beachte, dass es sich bei der Struktur um ein Beispiel handelt, aber die Eigenschaft Felder nicht die tatsächlichen Felder des Flows enthält.
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 (der angegebene Endpunkt hat einen HTTP-Code 200 zurückgegeben), kannst du deinen Webhook aktivieren. Jetzt wird jede Antwort auch als Post-Request an die URL gesendet.
Einen Webhook anpassen
Wenn du Business-Plan-Kunde bist, hast du viele Anpassungsmöglichkeiten, damit Webhooks in einer Vielzahl von Szenarien funktionieren.
Zunächst kannst du die Art der HTTP-Anfrage, die gestellt wird, anpassen. Außerdem kannst du benutzerdefinierte HTTP-Header angeben, die für deinen Endpunkt erforderlich sein könnten. Darüber hinaus kannst du zusätzlich zu den Antwortdaten benutzerdefinierte URL-Parameter wie API-Schlüssel oder ähnliches angeben. Und zu guter Letzt erlauben wir auch das Hinzufügen von HTTP Basic Auth-Anmeldedaten.
Zusätzlich zu diesen Optionen hast du auch die Möglichkeit, die Datenstruktur zu erweitern. Unten siehst du den Unterschied in der Payload, damit du entscheiden kannst, was für deinen Anwendungsfall besser geeignet ist.
Einfache Webhook-Payload
Normalerweise enthält der Webhook-Payload ein Objekt für Felder. In diesem Objekt sind die Schlüssel die System-Label, die für die Felder im Flow definiert sind, und der Wert entspricht der von den Nutzern gegebenen Antwort.
❗ 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.
{
flowID: <YourFlowID>,
id: <HeyflowResponseUUID>, // Heyflow UUID for the response
createdAt: <DateTimeOfTheResponseSubmission>, // new Date()
fields: {
"System Label": "Value"
},
}
Erweiterte Webhook-Payload
Im erweiterten Webhook-Payload stellen wir eine Menge zusätzlicher Metadaten für die Eigenschaft "Felder" bereit. Am wichtigsten ist, dass sich der Typ der Felder von einem Objekt zu einem Array von Objekten ändert.
{
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,
},
],
}
URL Parameter
Du kannst URL-Parameter hinzufügen, die an die Webhook-URL angehängt werden.
Beispiel: Deine Webhook-URL lautet https://www.example.com/webhookparty.
Wenn du deine URL-Parameter hinzufügst, würden wir eine Anfrage an https://www.example.com/webhookparty?test01=4711&test02=4812 senden.
Du kannst diese Funktion für feste Parameter verwenden. Stelle dir vor, du sendest einen Webhook an eine Lead-Ingestion-Engine. Diese haben in der Regel eine feste ClientID, die du hier eingeben würdest. Ein weiteres Beispiel wären API-Schlüssel.
❗ Hinweis: Du kannst keine Flowvariablen oder Daten, die in dem Flow eingegeben wurden, in den URL-Parametern verwenden.
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.