Verwenden Sie diesen Artikel, um das Wait for Webhook-Tool zu einer Fin-Prozedur hinzuzufügen, es so zu konfigurieren, dass es pausiert und auf die Antwort eines externen Systems wartet, und um Timeout- und Eskalationsverhalten einzurichten.
Wait for Webhook pausiert eine Fin-Prozedur und wartet darauf, dass ein externes System einen webhook sendet, eine automatisierte HTTP-Benachrichtigung, die ein System an ein anderes sendet, wenn ein bestimmtes Ereignis eintritt, bevor Fin fortfährt. Jede Konversation erhält eine einzigartige Callback-URL (eine dedizierte Webadresse, die Fin für diese Konversation generiert), die Ihr externes System verwendet, um seine Antwort an Fin zurückzusenden. So ist es möglich, mit Drittanbieterdiensten zu integrieren, die Anfragen asynchron verarbeiten – wie Identitätsprüfungsanbieter, Zahlungsabwickler oder Genehmigungssysteme – ohne den Kontext der laufenden Konversation zu verlieren.
Hinweis:
Wait for Webhook befindet sich derzeit in der Beta-Phase. Um es für Ihren Workspace zu aktivieren, kontaktieren Sie das Support-Team, um Zugang zu beantragen. Sie benötigen außerdem die Berechtigung can manage workspace data, um Fin-Prozeduren zu erstellen oder zu bearbeiten.
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 Prozedur 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 zurückzugeben.
Häufige Anwendungsfälle sind:
Identitäts- oder Altersprüfung – Warten auf die Bestätigung der Identität eines Kunden durch einen KYC (Know Your Customer)-Anbieter
Zahlungsautorisierung – Warten auf die Bestätigung einer Transaktion durch einen Zahlungsabwickler
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
Funktionsweise
Wenn Fin in einer Prozedur auf ein Wait for Webhook-Tool trifft, passiert Folgendes:
Fin generiert eine einzigartige Callback-URL für diese Konversation, wenn die Prozedur startet – nicht wenn die Ausführung das Wait for Webhook-Tool erreicht. Diese URL ist von Anfang an in jedem Schritt der Prozedur verfügbar.
Ihre Prozedur (über einen zuvor im Ablauf konfigurierten Data Connector) übergibt diese Callback-URL an Ihr externes System.
Das externe System schließt seine Verarbeitung ab und sendet seine Antwort an die Callback-URL.
Fin empfängt die Antwort, erfasst die Nutzlast in den in der Wait for Webhook-Tool-Konfiguration definierten Antwortattributen und setzt die Prozedur im nächsten Schritt fort.
Wenn innerhalb der konfigurierten Wartezeit kein Callback empfangen wird, löst Fin die Fallback-Aktion aus.
Wichtig: Die Callback-URL ist pro Prozedur-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 Prozedur hinzu
Öffnen Sie Ihre Prozedur 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:
Tool-Name
Geben Sie dem Tool einen beschreibenden Namen (zum Beispiel „Warten auf ID-Verifizierungs-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.
Beispielsweise, wenn Ihr Identitätsprüfungsanbieter einen status und eine reference_id zurücksendet, fügen Sie beide hier als Antwortattribute hinzu.
Hinweis: Als Antwortattribute werden nur skalare Zeichenkettenwerte unterstützt – ein skalare Wert ist ein einzelnes Textstück (zum Beispiel „verified“ oder „approved“), im Gegensatz zu Arrays oder verschachtelten JSON-Objekten. Wenn Ihr externes System eine komplexe verschachtelte Nutzlast sendet, wandeln Sie diese vor dem Senden des Callbacks in skalare Werte um. Antwortattribute müssen definiert sein, bevor der webhook ausgelöst wird, und können nicht nachträglich hinzugefügt werden, sobald die Prozedur live ist.
Wartezeit und Fallback
Legen Sie fest, wie lange Fin auf einen Callback warten soll, bevor es eskaliert. Wenden Sie sich für Details zu Mindest- und Höchstwartezeiten an Ihr Intercom-Kontoteam. Wenn innerhalb des konfigurierten Zeitfensters kein Callback empfangen wird, eskaliert Fin immer über einen festen Pfad – es gibt keine bedingte Verzweigung bei Timeout. Sie müssen im Konfigurations-Seitenpanel von Wait for Webhook zwei Dinge einrichten: eine Eskalationsnachricht, die an den Kunden gesendet wird, und einen Eskalationsbeauftragten (ein Team oder Teammitglied), an den die Konversation weitergeleitet wird.
Wichtig: Konfigurieren Sie im Seitenpanel immer sowohl eine Eskalationsnachricht als auch einen Eskalationsbeauftragten. 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 Prozedur startet – nicht wenn die Ausführung das Wait for Webhook-Tool erreicht. Das bedeutet, Sie können sie in jedem früheren Schritt an Ihr externes System übergeben, einschließlich des allerersten Schritts. Verwenden Sie dazu einen Data Connector.
Richten Sie einen Data Connector ein, der die API Ihres externen Systems aufruft (zum Beispiel einen „Start ID verification“-Endpunkt).
Fügen Sie in der Data Connector-Konfiguration einen Eingabeparameter hinzu und ordnen Sie ihn dem Callback-Attribut des webhook-Tools zu – dies ist die dynamisch generierte Callback-URL für diese Konversation.
Fügen Sie in Ihrer Prozedur vor dem Wait for Webhook-Tool einen Schritt zum Aufrufen des Data Connectors hinzu.
Wenn Fin den Data Connector aufruft, übergibt es die Callback-URL als Teil der Anfrage an Ihr externes System.
Ihr externes System speichert die Callback-URL und verwendet sie, um das Ergebnis per POST an Fin zurückzusenden, sobald die Verarbeitung abgeschlossen ist. Sobald der Callback empfangen wird, setzt Fin die Prozedur automatisch ab dem Wait for Webhook-Tool fort.
Hinweis: Der Data Connector-Schritt, der die Callback-URL übergibt, muss vor dem Wait for Webhook-Tool liegen. Da die URL ab dem Start der Prozedur verfügbar ist, kann Ihr Connector-Aufruf so früh im Ablauf erfolgen, wie Sie es benötigen.
So lesen Sie Antwortdaten nach dem Callback
Sobald Fin den webhook-Callback empfängt und die Prozedur fortsetzt, wird die Antwortnutzlast in den Antwortattributen erfasst, die Sie in der Wait for Webhook-Tool-Konfiguration 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 auf den erfassten Antwortattributen verzweigt haben, setzt die Prozedur 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, eskaliert Fin immer. Es gibt keine bedingte Verzweigung – Sie können kein unterschiedliches Verhalten je nach Timeout konfigurieren. Die Eskalation folgt immer diesen zwei Schritten:
Eskalationsnachricht: Die Nachricht, die Fin an den Kunden sendet, wenn das Timeout eintritt.
Eskalationsbeauftragter: Das Team oder Teammitglied, an das 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 Prozedur eingerichtet ist, verwenden Sie Simulationen im Prozedur-Editor, um den Wait for Webhook-Ablauf 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 Prozedurpfad fest, dem Fin folgen soll.
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 Eskalationspfad aus – es sendet die konfigurierte Eskalationsnachricht an den Kunden und leitet die Konversation an den Eskalationsbeauftragten weiter. Die Prozedur wird nicht fortgesetzt.
Wie übermittle ich die Callback-URL an mein externes System?
Wie übermittle ich die Callback-URL an mein externes System?
Verwenden Sie einen Data Connector-Schritt, der vor dem Wait for Webhook-Tool in Ihrer Prozedur 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 Prozedur-Durchlauf einzigartig und wird generiert, wenn die Prozedur startet – nicht wenn die Ausführung das Wait for Webhook-Tool erreicht. Jedes Mal, wenn eine Prozedur 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 Wait for Webhook-Tool-Konfiguration 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 in dem Link ab, den wir Ihnen gesendet haben.“ Ohne diese Information bleibt Fin mitten in der Konversation still, ohne dem Kunden eine Erklärung zu geben.