Webhooks sind ein Mechanismus, mit dem Daten bei bestimmten Ereignissen automatisch zwischen Websites und Anwendungen gesendet werden. Die Daten werden per HTTP-Anfrage übertragen: Eine Anwendung sendet sie über das Internet an eine zuvor festgelegte Adresse der anderen.
Möglichkeiten mit Webhooks
In FLOWIN arbeiten Webhooks mit Weiterleitungen zusammen. Sie können ausgelöst werden, wenn im ursprünglichen Chat (der Quelle) eine Nachricht erscheint, geändert, gelöscht oder angeheftet wird, sowie beim Klick auf einen Button im Chat, an den die Nachrichten weitergeleitet werden (dem Ziel).
So lässt sich FLOWIN mit sozialen Netzwerken, Börsen, Tabellen und CRM-Systemen (Systemen für die Kundenverwaltung) verbinden. Eine solche Verbindung heißt Integration und ermöglicht Folgendes:
- Anfragen aus Telegram automatisch in ein CRM übernehmen.
- Handelssignale aus Telegram an eine Börse zum automatischen Nachhandeln übertragen, also zur automatischen Ausführung von Geschäften anhand dieser Signale.
- Nachrichten aus Telegram an andere soziale Netzwerke weiterleiten.
- Beiträge und Nachrichten in Google Tabellen kopieren.
- Automatische Antworten in einem Bot einrichten.
Für jedes Szenario müssen der Datenempfang und die gewünschte Aktion aufseiten der Website oder Anwendung eingerichtet werden.
Einen Webhook erstellen
Wir testen den Webhook mit webhook.site. Diese Website stellt eine Adresse für den Datenempfang bereit und zeigt eingegangene Anfragen an. Dorthin senden wir den Text einer neuen Nachricht aus Telegram.
Dafür benötigen Sie eine eingerichtete und funktionierende Weiterleitung in FLOWIN.
Für den ersten Test
Verwenden Sie einen separaten Testchat und eine fiktive Anfrage. Für den Test genügt es, Text ohne Namen, Telefonnummern und andere personenbezogene Daten zu übertragen.
Öffnen Sie @flow_in_bot, senden Sie den Befehl
/startund klicken Sie auf „Dashboard“.
Zugang zum Dashboard über @flow_in_bot. Öffnen Sie webhook.site in einem separaten Tab. Kopieren Sie die Adresse zum Empfang von Anfragen aus dem Feld „Your unique URL“.
Adresse zum Empfang der Testanfrage. Öffnen Sie im FLOWIN-Dashboard „Menü“ → „Webhooks“ und klicken Sie auf „Erstellen“.
Der Bereich „Webhooks“ im FLOWIN-Menü. 
Den ersten Webhook erstellen. Fügen Sie die kopierte Adresse in das oberste Feld ein. Tragen Sie im Feld „Request-Body“
{"message":"<message-text>"}ein und klicken Sie auf „Erstellen“. Dies ist eine Vorlage für die zu sendenden Daten: Anstelle von<message-text>setzt FLOWIN den Nachrichtentext ein, den der Empfänger im Feldmessagesieht.
Adresse und Body der Testanfrage. Klicken Sie beim erstellten Webhook auf „Anwenden“. Markieren Sie die gewünschte Weiterleitung und klicken Sie auf „Speichern“.
Den Webhook mit einer Weiterleitung verbinden. 
Eine Weiterleitung für den Webhook auswählen. Senden Sie eine Testnachricht an den Quellchat, zum Beispiel: „Anfrage Nr. 1042: Ich brauche einen Möbelkatalog.“ Kehren Sie zu webhook.site zurück: Die erste eingegangene Anfrage öffnet sich automatisch. Im Bereich „Request Content“ erscheint der Text der Anfrage im Feld
message. FLOWIN sendet nun den Text jeder neuen Nachricht automatisch an die angegebene Adresse, bevor die Nachricht an den Zielchat weitergeleitet wird.
Die Testanfrage im Quellchat. 
Der empfangene Anfragetext auf webhook.site.
Webhook-Einstellungen
Am Beispiel des erstellten Webhooks sehen wir uns an, wie sich die Einstellungen ändern lassen und was die einzelnen Felder bedeuten.
Wo Sie die Einstellungen finden
Nutzen Sie die Dokumentation der anderen Website oder Anwendung, um sie anzubinden. Die Vorgaben für den Datenempfang stehen meist im Abschnitt zur API, der die Zusammenarbeit mit anderen Programmen beschreibt. Dort finden Sie Adresse, HTTP-Methode und Datenformat für die folgenden Felder.
Webhook-Einstellungen ändern
Klicken Sie in der Liste „Webhooks“ beim gewünschten Webhook auf „Ändern“.
Die Webhook-Einstellungen öffnen. Ändern Sie die gewünschten Felder und klicken Sie auf „Speichern“.
Die geänderten Einstellungen speichern. 
Die Beschreibung ist in den Webhook-Einstellungen gespeichert.
HTTP-Methode
Die HTTP-Methode legt die Aktion der Anfrage fest: POST übermittelt Daten zur Verarbeitung, GET fragt Daten ab und PUT ersetzt sie. Standardmäßig ist POST ausgewählt, das für unseren Test geeignet ist. Wählen Sie für eine andere Website oder Anwendung die Methode aus deren Dokumentation.
URL-Adresse
Eine URL ist eine Adresse im Internet. Hier wird die Adresse zum Datenempfang eingetragen, die Sie von der angebundenen Website oder Anwendung erhalten haben. In unserem Beispiel stammt sie von webhook.site.
Request-Body
Der Request-Body enthält die zu sendenden Daten im JSON-Format als Paare aus „Feldname: Wert“. Welche Felder benötigt werden, hängt von den Anforderungen der angebundenen Website oder Anwendung ab.
Metatags sind Platzhalter, die FLOWIN durch Daten der Nachricht ersetzt. Zum Beispiel wird <message-text> durch den Text ersetzt und <author-name> durch den Namen des Autors. Die Liste der Metatags lässt sich auch über den Link „Metatags“ unter dem Feld öffnen.
Die Nummern von Nutzern, Nachrichten, Chats und Themen in der folgenden Liste bezeichnen deren Kennungen (IDs) in Telegram.
Nachricht und Autor
- Nachrichtentext:
<message-text>. - Datum der Nachricht:
<message-date>. - Uhrzeit der Nachricht:
<message-time>. - Nummer des Autors:
<author-id>. - Name des Autors:
<author-name>. - Name des Autors als HTML-Link zu seinem Profil:
<author-name-link>. - Name des Autors als Hashtag:
<author-name-tag>. - Benutzername des Autors:
<author-username>.
Quelle
- Nachrichtentext:
<src-message-text>. - Nummer der Nachricht:
<src-message-id>. - Link zur Nachricht:
<src-message-link>. - Nummer des Chats:
<src-chat-id>. - Name des Chats:
<src-chat-name>. - Benutzername des Chats:
<src-chat-username>. - Nummer des Themas:
<src-topic-id>. - Name des Themas:
<src-topic-name>.
Ziel
- Nachrichtentext:
<dst-message-text>. - Nummer der Nachricht:
<dst-message-id>. - Link zur Nachricht:
<dst-message-link>. - Nummer des Chats:
<dst-chat-id>. - Name des Chats:
<dst-chat-name>. - Benutzername des Chats:
<dst-chat-username>. - Nummer des Themas:
<dst-topic-id>. - Name des Themas:
<dst-topic-name>.
Nummer und Link der Nachricht im Ziel stehen nach der Weiterleitung zur Verfügung. Um sie zu übertragen, wählen Sie „Nach dem Senden“ im Feld „Anfrage-Trigger“.
Button-Klick
- Nummer des Nutzers, der geklickt hat:
<clicker-id>. - Name des Nutzers, der geklickt hat:
<clicker-name>. - Daten des Buttons:
<clicker-data>. - Datum des Klicks:
<click-date>. - Uhrzeit des Klicks:
<click-time>.
Textauswahl
- Ein regulärer Ausdruck legt eine Regel zur Textsuche fest. Zum Beispiel setzt
<regexp>(short|sell)</regexp>den ersten gefundenen Treffer fürshortodersellein. - Mit
<random>1|2|3|4|5</random>wird zufällig eine der fünf Varianten eingesetzt. Zwischen den Tags können Sie eigene Varianten angeben und sie durch das Zeichen|trennen.
Request-Header
Die „Request-Header“ enthalten technische Angaben für den Empfänger. Ein Zugangsschlüssel ermöglicht beispielsweise die Prüfung, wer die Anfrage gesendet hat. Die Header werden im JSON-Format angegeben. Dieses Feld muss normalerweise nicht geändert werden; die benötigten Werte stehen in der Dokumentation der angebundenen Website oder Anwendung.
Anfrage-Trigger
Der „Anfrage-Trigger“ bestimmt das Ereignis und den Zeitpunkt, zu dem der Webhook eine Anfrage an die angegebene Adresse senden soll. Folgende Ereignisse stehen zur Auswahl:
- „Senden“ ist standardmäßig ausgewählt. Der Webhook wird beim Weiterleiten einer neuen Nachricht ausgelöst.
- „Bearbeiten“ wird ausgelöst, wenn eine Änderung einer Nachricht in der Quelle verarbeitet wird.
- „Anheften“ wird ausgelöst, wenn das Anheften einer Nachricht in der Quelle verarbeitet wird.
- „Löschen“ wird ausgelöst, wenn das Löschen einer Nachricht in der Quelle verarbeitet wird.
- „Button-Klick“ wird bei Buttons mit Rückruf (Callback) im Zielchat ausgelöst. Ein solcher Button informiert den Bot über den Klick und übermittelt die für ihn festgelegten Daten. Ein gewöhnlicher Button mit einem Link löst diesen Webhook nicht aus.
Der Sendezeitpunkt legt fest, in welcher Phase der Weiterleitung die Anfrage gesendet wird:
- „Vor der Verarbeitung“: Die Anfrage wird vor der Übersetzung und der Verarbeitung der Nachricht durch künstliche Intelligenz (KI) gesendet.
- „Nach der Verarbeitung“: Die Anfrage wird nach der Übersetzung und der KI-Verarbeitung gesendet.
- „Nach dem Senden“: Die Anfrage wird gesendet, wenn die Nachricht bereits erfolgreich im Zielchat gesendet oder geändert wurde.
Verfügbare Sendezeitpunkte
Alle drei Optionen sind für die Ereignisse „Senden“ und „Bearbeiten“ verfügbar. Für „Anheften“, „Löschen“ und „Button-Klick“ wird „Vor der Verarbeitung“ verwendet; ein anderer Zeitpunkt kann nicht ausgewählt werden.
Beschreibung
Die „Beschreibung“ dient als Kommentar zu Ihrer Orientierung und hat keinen Einfluss auf die Funktion des Webhooks. Das Feld kann leer bleiben.
Verfügbare Aktionen für Webhooks
Erstellte Webhooks lassen sich über die Liste „Webhooks“ verwalten:
- „Ändern“ öffnet die Grundeinstellungen des Webhooks.
- „Duplizieren“ im Menü „Mehr“ erstellt eine Kopie der Webhook-Einstellungen.
- „Projekt auswählen“ im Menü „Mehr“ fügt den Webhook einem Projekt hinzu.
- „Löschen“ im Menü „Mehr“ löscht den Webhook.
Außerdem verfügt jeder Webhook über die Schaltfläche „Weiterleitungen [N]“. Sie öffnet die Auswahl der Weiterleitungen, auf die er angewendet wird. N steht für die Anzahl der ausgewählten Weiterleitungen. Sind noch keine Weiterleitungen ausgewählt, wird stattdessen die Schaltfläche „Anwenden“ angezeigt.
Häufige Fragen
Was ist ein Webhook, einfach erklärt?
Ein Webhook überträgt bei einem bestimmten Ereignis automatisch Daten an eine andere Anwendung. Beim Weiterleiten einer neuen Nachricht sendet FLOWIN beispielsweise deren Text per HTTP-Anfrage an die von Ihnen angegebene Adresse. Hier sendet FLOWIN die Anfrage; die Telegram-Methode setWebhook richtet die andere Richtung ein: die Zustellung von Updates von Telegram an das Programm, das den Bot betreibt.
Genügt es, die Adresse des CRM anzugeben?
Nein. Sie benötigen die Adresse für den Datenempfang aus der CRM-Dokumentation sowie die passende HTTP-Methode, JSON-Felder und Header, falls diese für den Zugriff erforderlich sind. Die gewöhnliche Website-Adresse des CRM eignet sich dafür nicht. FLOWIN sendet die Anfrage; ob eine Kundenanfrage angelegt oder eine andere Aktion ausgeführt wird, hängt davon ab, wie das CRM die empfangenen Daten verarbeitet. Die Feldwerte werden im Abschnitt „Webhook-Einstellungen“ beschrieben.
Warum ist der Link zur Nachricht im Ziel leer?
Bevor eine neue Nachricht erfolgreich gesendet wurde, hat FLOWIN noch keine Nummer und keinen Link für sie im Ziel. Um <dst-message-id> und <dst-message-link> zu übertragen, wählen Sie das Ereignis „Senden“ oder „Bearbeiten“ und den Zeitpunkt „Nach dem Senden“ im Feld „Anfrage-Trigger“. Der Link wird für Kanäle und Supergruppen gebildet. Bei einem privaten Chat oder einer gewöhnlichen Gruppe bleibt <dst-message-link> auch nach dem Senden leer.
Lässt sich ein Webhook durch einen gewöhnlichen URL-Button auslösen?
Nein. Ein gewöhnlicher URL-Button öffnet einen Link. Für das Ereignis „Button-Klick“ ist ein Button mit Rückruf (Callback) im Zielchat erforderlich: Er übermittelt dem Bot Daten über den Klick. Dieser Unterschied wird im Abschnitt „Anfrage-Trigger“ beschrieben.
Wie lässt sich prüfen, ob der externe Dienst die Daten erhalten hat?
Senden Sie eine fiktive Nachricht und prüfen Sie die eingegangene Anfrage beim Dienst. Im Beispiel mit webhook.site erscheint der Anfragetext im Bereich „Request Content“. Eine erfolgreiche Weiterleitung in Telegram allein bestätigt nicht, dass der externe Dienst die Daten angenommen oder die gewünschte Aktion ausgeführt hat. Für den Test genügt Text ohne Namen, Telefonnummern und andere personenbezogene Daten.