Verwenden Sie diesen Artikel, um das Wait for Webhook-Tool in einer Fin Procedure einzurichten, zu konfigurieren, wie lange Fin auf die Antwort eines externen Systems wartet, und um Probleme zu beheben, falls kein Callback eintrifft. Das Wait for Webhook-Tool pausiert Fin mitten in der Procedure, damit es auf externe Eingaben von Systemen warten kann, die Anfragen asynchron verarbeiten, wie Identitätsprüfungsanbieter (z. B. Onfido) oder Zahlungs- und Bankintegrationen (z. B. Plaid), bevor es fortfährt.
Hinweis:
Wait for Webhook ist nur innerhalb von Instruction-Schritten verfügbar. Fügen Sie es hinzu, indem Sie @ in einem Instruction-Schritt eingeben und Wait for Webhook aus dem Tool-Auswahlmenü wählen.
Wann Sie Wait for Webhook verwenden sollten
Verwenden Sie dieses Tool, wenn Ihre Procedure an ein externes System übergeben werden muss und auf ein Ergebnis warten soll, bevor sie fortfährt – und dieses System Anfragen asynchron verarbeitet, anstatt sofort eine Antwort zu geben.
Häufige Anwendungsfälle sind:
Identitäts- oder Altersprüfung – Warten auf die Bestätigung der Identität eines Kunden durch einen KYC-Anbieter (Know Your Customer)
Zahlungsautorisierung – Warten auf die Bestätigung einer Transaktion durch einen Zahlungsprozessor
Kontoverknüpfung – Warten auf den Abschluss eines OAuth-(Open Authorization Standard)-Flows
Auftragsabwicklungskontrollen – Warten auf die Bestätigung der Lagerverfügbarkeit durch ein Lagersystem
Genehmigungsworkflows – Warten auf die Genehmigung einer Rückerstattung oder Ausnahme durch ein internes Team
Was passiert, wenn Fin das Wait for Webhook-Tool erreicht
Wenn Fin ein Wait for Webhook-Tool in einer Procedure erreicht, passiert Folgendes:
Wenn ein Procedure-Durchlauf startet, generiert Fin für jedes Wait for Webhook-Tool eine eindeutige Callback-URL.
Konfigurieren Sie Ihre Procedure so, dass diese Callback-URL vor Erreichen des Wait for Webhook-Tools mithilfe eines Data Connectors an Ihr externes System übergeben wird.
Sobald das externe System seine Verarbeitung abgeschlossen hat und einen webhook an die Callback-URL sendet, erfasst Fin die webhook-Nutzlast in den konfigurierten Antwortattributen und setzt die Procedure automatisch fort.
Wenn innerhalb der konfigurierten Wartezeit kein Callback empfangen wird, sendet Fin die konfigurierte Eskalationsnachricht und weist die Konversation dem konfigurierten Eskalationsbeauftragten zu.
Wichtig: Die Callback-URL ist pro Procedure-Durchlauf einzigartig. Sie kann nicht für mehrere Konversationen wiederverwendet oder als statischer Endpunkt gespeichert werden.
So fügen Sie Wait for Webhook zu einer Procedure hinzu
Öffnen Sie Ihre Procedure im Editor.
Geben Sie in einem Instruction-Schritt @ ein, um das Tool-Auswahlmenü zu öffnen.
Wählen Sie Wait for Webhook aus der Liste aus.
Das Wait for Webhook-Tool wird in den Schritt eingefügt und ein Konfigurations-Seitenpanel öffnet sich rechts.
So konfigurieren Sie das Tool
Das Konfigurations-Seitenpanel für Wait for Webhook hat drei Felder:
Toolname
Geben Sie dem Tool einen beschreibenden Namen (zum Beispiel „Wait for ID verification callback“). Dieser Name identifiziert das Tool im Editor und wird referenziert, wenn Sie die Callback-URL als Parameter in Ihrem Data Connector zuordnen.
Antwortattribute
Definieren Sie die Felder, die das externe System in seiner webhook-Nutzlast enthalten soll. Jedes hier definierte Attribut wird erfasst, wenn der Callback eintrifft, und kann in späteren Schritten mit dem Read attribute-Tool referenziert werden.
Wenn Ihr Identitätsprüfungsanbieter beispielsweise einen status und eine reference_id zurücksendet, fügen Sie beide hier als Antwortattribute hinzu.
Wartezeit und Fallback
Legen Sie fest, wie lange Fin auf einen Callback warten soll, bevor eskaliert wird. Sie müssen auch die Eskalationsnachricht konfigurieren, die an den Kunden gesendet wird, und den Beauftragten auswählen, an den die Konversation bei Erreichen des Timeouts weitergeleitet wird.
Wichtig: Konfigurieren Sie immer sowohl eine Eskalationsnachricht als auch einen Eskalationsbeauftragten im Seitenpanel. Wenn eines fehlt, kann das Timeout-Verhalten unvorhersehbar sein.
So übergeben Sie die Callback-URL an Ihr externes System
Die Callback-URL wird generiert, wenn die Procedure startet – nicht wenn die Ausführung das Wait for Webhook-Tool erreicht. Das bedeutet, Sie können sie in jedem früheren Schritt übergeben, auch im allerersten Schritt. Verwenden Sie dazu einen Data Connector.
Richten Sie einen Data Connector ein, der die API Ihres externen Systems aufruft (z. B. einen „Start ID Verification“-Endpunkt).
Konfigurieren Sie den Data Connector so, dass er eine Callback-URL als Eingabeparameter akzeptiert.
Ordnen Sie in der Procedure-Editor diesen Eingabeparameter dem URL-Attribut des webhook-Tools zu.
Stellen Sie sicher, dass die Procedure so eingerichtet ist, dass dieser Data Connector vor dem Erreichen des Wait for Webhook-Tools aufgerufen wird.
Wenn Fin den Data Connector aufruft, übergibt es die eindeutige Callback-URL in der Anfrage. Ihr externes System speichert diese URL und sendet den webhook-Callback an sie, sobald die Verarbeitung abgeschlossen ist.
Hinweis: Der Aufruf des Data Connectors, der die Callback-URL übergibt, muss vor dem Wait for Webhook-Tool erfolgen. So erhält das externe System Zugriff auf die Callback-URL.
So lesen Sie Antwortdaten nach dem Callback
Sobald Fin den webhook-Callback erhält und die Procedure fortsetzt, wird die Antwortnutzlast in den Antwortattributen erfasst, die Sie in der Konfiguration des Wait for Webhook-Tools definiert haben. Verwenden Sie das Read attribute-Tool in einem nachfolgenden Instruction-Schritt, um auf diese Werte zuzugreifen.
Zum Beispiel:
Lesen Sie verification_status, um zu prüfen, ob die Identitätsprüfung bestanden oder fehlgeschlagen ist.
Verwenden Sie einen Condition-Schritt, um den Ablauf basierend auf dem Ergebnis zu verzweigen.
Übergeben Sie Werte aus der Antwort an einen anderen Data Connector zur weiteren Verarbeitung.
Sobald das Wait for Webhook-Tool seinen Callback erhalten hat und Sie basierend auf den erfassten Antwortattributen verzweigt haben, setzt die Procedure ihren nächsten Schritt normal fort. Wenn der Callback innerhalb der konfigurierten Wartezeit nie eintrifft, eskaliert Fin wie unter „Was passiert, wenn die Wartezeit abläuft?“ beschrieben.
Was passiert, wenn die Wartezeit abläuft?
Wenn die konfigurierte Wartezeit des Wait for Webhook-Tools abläuft, ohne dass ein Callback empfangen wird, übergibt Fin immer weiter – es gibt keine bedingte Verzweigung beim Timeout selbst. Der Kunde sieht zuerst die konfigurierte Timeout-Nachricht, dann wird die Konversation an das konfigurierte Ziel übergeben:
Eskalationsnachricht: Die Nachricht, die Fin an den Kunden sendet, wenn das Timeout eintritt.
Eskalationsbeauftragter: Das Team oder der Kollege, an den die Konversation nach dem Senden der Nachricht weitergeleitet wird.
Tipp:
Stellen Sie Ihre Wartezeit so ein, dass sie der erwarteten Verarbeitungszeit Ihres externen Systems entspricht, mit einem angemessenen Puffer. Wenn Ihr Anbieter typischerweise in 10 Sekunden antwortet, bietet eine Wartezeit von 60 Sekunden einen sicheren Spielraum und hält die Erfahrung reaktionsschnell.
Sobald Ihre Procedure eingerichtet ist, verwenden Sie Simulationen im Procedure-Editor, um den Wait for Webhook-Fluss von Anfang bis Ende zu validieren, bevor er echte Kunden erreicht. Definieren Sie eine simulierte Callback-Nutzlast in der Simulation und legen Sie Erfolgskriterien basierend auf dem erwarteten Procedure-Pfad fest, dem Fin folgen soll.
Wichtig: In der Vorschau und im Testmodus wartet dieser Schritt nicht auf einen echten webhook-Callback – er wird sofort mit dem konfigurierten Standardwert jedes Attributs aufgelöst. Um das echte Warte-/Timeout-Verhalten zu testen, verwenden Sie Simulationen oder wenden Sie sich an den Support, um Live-Vorschau-Callbacks für Ihren Workspace zu aktivieren.
Was sind die Einschränkungen des Wait for Webhook-Tools?
Das Wait for Webhook-Tool hat in seiner aktuellen Version folgende Einschränkungen:
Nur skalare Werte: Antwortattribute unterstützen nur Text- und Zahlenwerte. Arrays und verschachtelte JSON-Objekte in der webhook-Nutzlast werden nicht erfasst.
Groß-/Kleinschreibung bei Attributnamen: Der Name eines Antwortattributs muss genau mit dem entsprechenden Schlüssel in der webhook-Nutzlast übereinstimmen. Stimmen die Namen nicht überein, wird der Wert nicht erfasst – und es wird kein Fehler angezeigt. Prüfen Sie daher die Attributnamen sorgfältig, wenn ein Wert leer zurückkommt.
Wiederverwendung der Callback-URL bei Rückschleifen: Wenn eine Procedure in einem einzelnen Durchlauf mehrmals zum gleichen Wait for Webhook-Tool zurückkehrt, wird dieselbe Callback-URL für dieses Tool wiederverwendet.
Getrennt von Workflows: Das Wait for Webhook-Tool in Fin Procedures ist eine separate Implementierung vom Wait for Webhook-Schritt in Workflows. Die Konfiguration wird nicht geteilt oder wiederverwendet.
FAQs
Mein webhook ist nie angekommen – was passiert?
Mein webhook ist nie angekommen – was passiert?
Wenn innerhalb der konfigurierten Wartezeit kein Callback empfangen wird, löst Fin den Timeout-Pfad aus – es sendet die konfigurierte Timeout-Nachricht an den Kunden und übergibt an das konfigurierte Ziel, das ein Team oder ein workflow sein kann. Die Procedure wird nicht fortgesetzt; wenn die Übergabe an einen workflow erfolgt, entscheidet dieser, was als Nächstes passiert, und die Procedure wird nicht wieder aufgenommen.
Wie bekomme ich die Callback-URL zu meinem externen System?
Wie bekomme ich die Callback-URL zu meinem externen System?
Verwenden Sie einen Data Connector-Schritt, der vor dem Wait for Webhook-Tool in Ihrer Procedure platziert ist. Konfigurieren Sie den Connector so, dass er die API Ihres externen Systems aufruft und das Callback-Attribut des webhook-Tools als Eingabeparameter zuordnet. Fin übergibt die Callback-URL an das externe System, wenn der Connector aufgerufen wird, sodass das System weiß, wohin es den Callback senden soll.
Kann ich dieselbe Callback-URL für mehrere Konversationen verwenden?
Kann ich dieselbe Callback-URL für mehrere Konversationen verwenden?
Nein. Die Callback-URL ist pro Procedure-Durchlauf einzigartig und wird generiert, wenn die Procedure startet – nicht wenn die Ausführung das Wait for Webhook-Tool erreicht. Jedes Mal, wenn eine Procedure für einen Kunden ausgeführt wird, wird eine neue URL generiert. Sie können sie nicht als statischen Endpunkt speichern oder für mehrere Konversationen wiederverwenden.
Welche Nutzlastfelder kann mein externes System zurücksenden?
Welche Nutzlastfelder kann mein externes System zurücksenden?
Ihr externes System kann beliebige Felder in der webhook-Nutzlast enthalten, aber nur die Felder, die Sie als Antwortattribute in der Konfiguration des Wait for Webhook-Tools definiert haben, werden von Fin erfasst und in nachfolgenden Schritten verfügbar gemacht. Alle zusätzlichen Felder in der Nutzlast werden ignoriert.
Was passiert, während Fin auf einen Callback wartet?
Was passiert, während Fin auf einen Callback wartet?
Während Fin pausiert und auf einen webhook-Callback wartet, reagiert es nicht auf eingehende Kundenmeldungen. Die Konversation ist effektiv still, bis der Callback eintrifft oder das Timeout eintritt.
Tipp: Fügen Sie immer einen Instruction-Schritt vor dem Wait for Webhook-Tool hinzu, um dem Kunden mitzuteilen, was passiert – zum Beispiel: „Wir überprüfen Ihre Identität. Bitte schließen Sie den Schritt im Link ab, den wir Ihnen gesendet haben.“ Ohne diese Information bleibt Fin mitten in der Konversation still, ohne Erklärung für den Kunden.
Welche Berechtigungen benötige ich, um Wait for Webhook zu verwenden?
Welche Berechtigungen benötige ich, um Wait for Webhook zu verwenden?
Sie benötigen die Berechtigung can manage workspace data, um Fin Procedures zu erstellen oder zu bearbeiten, einschließlich des Hinzufügens des Wait for Webhook-Tools. Sie können Berechtigungen unter Einstellungen > Workspace > Teammates prüfen und aktualisieren.