FileMaker und Webhooks
Was sind Webhooks? Wo liegen die Vor- und Nachteile und was hat das alles mit FileMaker zu tun? Das will ich hiermit heute erklären!
Im FileMaker Magazin Forum berichtet Benutzer Arthur, dass er Bestellungen von einem WooCommerce Webshop in FileMaker verarbeiten soll und ihm der Webshop Programmierer die Daten per Webhook übergeben möchte. Konkret fragt er:
Wie kriege ich eine funktionierende Webhook-Adresse aus dem Filemaker? Oder gibt es ein Plugin womit ich das Szenario abbilden kann?
Arthur aus dem FileMaker Magazin Forum
Was sind Webhooks?
Klären wir zunächst, was Webhooks sind:
Per Webhook informiert ein Webserver oder -dienst über ein Ereignis. Beispielsweise informiert WooCommerce per Webhook, dass eine Bestellung eingegangen ist und sendet dabei die Bestelldaten mit.
In einem anderen Szenario informiert ein SMS-Modem über eingehende SMS, damit diese “von uns” weiterverarbeitet werden können. “Von uns” heißt im konkreten Fall, dass wir als Webprogrammierer/FileMaker Programmierer die Daten vom Dienst entgegennehmen und dann entsprechend darauf reagieren können. Im Falle von eingehenden SMS werden wir die Nachricht dem korrekten Mitarbeiter am Bildschirm präsentieren und im Falle der eingehenden Bestellung den Versand der Ware veranlassen.
Ein Webhook ist also eine Schnittstelle zwischen zwei Computersystemen.
Wir als Dienst-Konsument hinterlegen beim Diensteanbieter (also zB dem Webshop) eine Webhook-URL. Der Diensteanbieter ruft diese URL dann bei entsprechenden Ereignissen auf und übergibt zusätzliche Daten, wie eben die Bestellinfos. Welche Daten übergeben werden, ist natürlich von Dienst zu Dienst unterschiedlich und lässt sich der jeweiligen Dokumentation entnehmen.
Die Webhook-URL müssen wir als Programmierer beim Dienst hinterlegen.
Wir werden weiter unten klären, wie wir zu dieser Webhook-URL kommen.
Da der Dienste-Anbieter unsere Webhook-URL aktiv aufruft, wird dieses Verfahren gerne als Push-API bezeichnet.
Die exakte Definition lässt sich natürlich bei Wikipedia nachlesen.
Alternativen zu Webhooks
Stehen keine Webhooks zur Verfügung, so müssen wir den Dienst regelmäßig befragen, ob neue Daten (also neue Bestellungen, neue SMS, etc.) zur Verfügung stehen.
Hier könnte man zum Beispiel per FileMaker Server Script alle 5 Minuten beim Webshop anfragen, ob neue Bestellungen vorliegen.
Dieses Verfahren nennt man Polling.
Vor- und Nachteile von Webhooks und Polling
Webhooks sind schnell
Ein großer Vorteil von Webhooks ist die Geschwindigkeit, mit der die Daten weiterverarbeitet werden. SMS geht ein, Webhook wird aufgerufen, SMS wird von unserem System sofort weiterverarbeitet.
Beim Polling würde die Nachricht unter Umständen erst 4 Minuten 50 Sekunden später weiterverarbeitet werden, wenn wir z.B. ab 0 Uhr alle 5 Minuten die Nachrichten pollen und eine SMS um 12:00:10 eingeht, dann wird diese erst beim Abruf um 12:05 berücksichtig.
Nun könnte man natürlich das Pollingintervall verringern und eingehende Nachrichten jede Minuten abrufen, aber das würde vermutlich eine hohe Last am eigenen (FileMaker)-server sowie am Fremdsystem verursachen. Und das Intervall noch weiter zu verringern, z.B. ein Abruf der Daten alle 5 Sekunden, erscheint noch viel unpraktikabler.
Webhooks sind ressourcenschonend
Da Webhooks nur bei tatsächlichen Ereignissen aufgerufen werden, wird das eigene (FileMaker)-System wirklich nur beansprucht, wenn es Daten zu verarbeiten gibt. Beim Pollingverfahren hingegen müssen die System alle paar Minuten kommunizieren, egal ob es neue Daten gibt oder nicht.
Webhooks können zu Datenverlust führen
Ein Nachteil von Webhooks ist, dass das aufrufende System unsere URL aufruft und erwartet, dass wir diese Nachricht korrekt weiterverarbeiten. Sollte unser Server gerade offline sein weil er neu bootet oder die Internetleitung ist wegen einer kurzen Störung tot, so können wir die Nachricht nicht empfangen und verarbeiten. Datenverlust droht.
In der Praxis wird das durch 2 Maßnahmen entschärft / gelöst:
1.) Wenn die Webhook-URL aufgerufen wird, so müssen wir als Programmierer einen HTTP-Statuscode “OK” zurückgeben. Dann weiß der Diensteanbieter, dass wir die Nachricht bekommen haben und ist nicht weiter dafür verantwortlich. Somit müssen wir als Programmierer darauf achten, das “OK” wirklich nur zu senden, wenn die Nachricht vollständig und fehlerfrei in FileMaker gespeichert werden konnte.
2.) Wenn unser Webserver nicht mit einem “OK” antwortet, sondern gar nicht (Timeout) oder mit einem anderen Code (z.B. HTTP-Code 500 / Internal Server Error) so probieren die meisten Diensteanbieter, den Webhook erneut aufzurufen. Der Zahlungsdienstleister Square beispielsweise ruft Webhooks nach folgendem Schema erneut auf:
- 1.Retry nach 1 Minute
- 2.Retry nach 2 Minuten
- 3.Retry nach 7 Minuten
- 4.Retry nach 15 Minuten
- 5.Retry nach 31 Minuten
- 6.Retry nach 63 Minuten
- 7.-78.Retry nach 2 bis 72 Stunden
- Danach verfällt die Nachricht
Zu beachten ist, dass fast jeder Dienst, der Webhooks anbietet, auch Retries implementiert hat, aber Ausnahmen bestätigen die Regel.
Sicherheitshinweis
Beim Webhook bekommt man Daten von einem Fremdsystem und verarbeitet diese weiter. Hier ist es wichtig zu prüfen, dass die Daten wirklich von einer vertrauenswürdigen Absenderadresse stammen. Man könnte zB die Webhook-URL per Firewall Regel nur für spezielle Absender freigeben oder die transportierte Nachricht wird digital signiert etc.
Webhooks benötigen einen online erreichbaren Webserver
Da Webhooks über das http(s) Protokoll URLs aufrufen, muss unser Webserver rund um die Uhr online und erreichbar sein.
Beim Pollingverfahren hingegen bauen wir die Verbindung zum Dienstanbieter auf, um von dort Daten abzurufen. Wir machen das nach unseren (Firewall)regeln und nach unserem Zeitplan. Es ist nicht notwendig, 24/7 online zu sein.
Was ist besser? Webhooks oder Polling?
Beides klappt! Beides ist gut! Je nach Szenario ist die eine Variante praktikabler als die andere. Außerdem schließen sich beide ja nicht aus. Die meisten Diensteanbieter, die Webhooks erlauben, haben auch REST-APIs. Man kann also meistens beides verwenden.
Eine wirklich gute Erklärung findet sich auf der Webseite von Mailchimp.
Wie kommt man nun zu einer Webhook-URL?
Das Ganze sei nun an einem Beispiel mit der Programmiersprache PHP erklärt. In der Praxis können Sie natürlich andere Sprachen wie Ruby, Java, Python, C# etc. verwenden. PHP ist einfach, weit verbreitet und bei 99% aller Webhostinganbieter im Preis enthalten.
eTermin Beispiel
Vor einiger Zeit durfte ich für eine Arztpraxis eTermin anbinden. Wann immer ein Patient einen Termin über die eTermin Webseite buchte, wurden die Buchung per Webhook in FileMaker eingetragen. Daher zeige ich nun dieses Script.
Im eTermin Webinterface muss man die Webhooks konfigurieren. eTermin bezeichnet diese als “Web Push”. Hierbei habe ich die URL https://www.schubec.com/etermin/index.php hinterlegt. Als Format habe ich JSON ausgewählt, siehe Screenshot.
Am wwww.schubec.com Webserver lege ich ein Verzeichnis etermin an, darin eine Datei index.php mit folgendem Inhalt:
<?php
require_once './vendor/autoload.php';
use INTERMediator\FileMakerServer\RESTAPI\FMDataAPI as FMDataAPI;
define('FM_HOST', 'etermin.fm-server.net');
define('FM_DATABASE', 'eTerminDemo');
define('FM_USER', 'eTerminWebhook');
define('FM_PASSWORD', 'das-passwort-ist-natürlich-geheim');
$json = file_get_contents('php://input');
$fmdb = new FMDataAPI(FM_DATABASE, FM_USER, FM_PASSWORD, FM_HOST);
$data=[];
$data['JSON']=$json;
$fmdb->layout('Webhook')->create($data, null, array('script'=>'eTermin_Webhook'));
Um die Verbindung vom Webserver zum FileMaker Server aufzubauen, wird die kostenlosen PHP-Bibliothek FMDataAPI von INTERMediator verwendet. Diese wird in den ersten paar Zeilen geladen.
Danach definieren wir die FileMaker Zugangsdaten, also FileMaker Server Name, Datenbank, Benutzername und Passwort.
Mit file_get_contents('php://input') lesen wir die Daten vom Webhook in die Variable $json.
Danach sagen wir, dass der Inhalt von $json im FileMaker Feld JSON in einem neuen Datensatz im Layout Webhook angelegt und dann sofort das Script eTermin_Webhook aufgerufen werden soll. Das war es hier auch schon!
Wie Sie hier sehen (bzw. nicht sehen), nehmen wir die JSON Daten von eTermin entgegen und speichern diese unverändert in FileMaker. Es findet in diesem Beispiel keinerlei Verarbeitung der JSON Daten in PHP statt! (Die Verarbeitung findet in FileMaker im Script eTermin_Webhook statt.)
Da wir keinen expliziten Status zurückgeben, sendet PHP automatisch ein “OK” an den aufrufenden Server. Und im Fehlerfall, zum Beispiel weil wir uns beim FileMaker Passwort vertippt haben, sorgt die PHP-Bibliothek von INTERMediator dafür, dass eine Exception (ein Fehler) ausgegeben wird.
eTermin bietet nun an, ein Web Push (CREATED) mit Testwerten zu senden. Das sollten Sie nun unbedingt ausprobieren und schauen, ob der Termin korrekt in FileMaker ankommt.
Gratulation – ihr erster FileMaker-Webhook!
Download
Hier können Sie das Codebeispiel samt benötigter Bibliotheken herunterladen. Für die einfachere Nutzung inkl. der Composerdaten, sodass Sie das ganze nur auf Ihrem PHP-Webserver extrahieren und die Konfiguration anpassen müssen.
Hinweis
Das eTermin Beispiel ist aus dem Jahr 2021 und SOLLTE funktionieren. Ich habe es aktuell nicht ausprobiert, weil ich beim Kundenaccount nichts ändern wollte und ich keinen eigenen eTermin Account habe. Sollten Sie das ganze tatsächlich mit eTermin probieren und es klappt nicht, so kontaktieren Sie mich kurz, damit wir das Problem gemeinsam lösen und ich hier das Script aktualisieren kann!
Der PHP Code ist unklar?
Anfänger mögen mit dem Codeschnippsel Probleme haben, das ist mir klar. Vor allem, weil die Bibliothek für den Zugriff auf FileMaker per Composer installiert werden muss.
Das alles hier zu erklären würde den Rahmen bei weitem sprengen. Aber fragen Sie den Webprogrammierer Ihrer Wahl (oder das IT-affine Nachbarskind), der wird mit diesem Codeschnippsel vermutlich in 5 Minuten die Anbindung hinbekommen.
Ich biete auch immer wieder FileMaker und PHP-Schulungen an, wo ich diese Grundlagen und natürlich viele weitere Themen wie z.B. die Konfiguration von FileMaker Server und den Datenbanken inkl. Zugriffsrechte erkläre. Am besten Sie abonnieren den Newsletter oben rechts, damit Sie keine Schulungsinfos verpassen!
Praxis
Dieses PHP-Script funktioniert und ist vollständig. In der Praxis logge ich meist eingehende Webhook-Daten in eine Datei weg, um die Fehlersuche zu erleichtern.
Außerdem filtere ich oft eingehende Nachrichten. Bei meinem SMS-Modem verarbeite ich zum Beispiel erfolgreich versendete SMS sowie SMS die nicht versendet werden konnten. Dass das Modem bis zu drei mal versucht eine SMS zuzustellen und dafür jedes Mal eine Webhook-Nachricht generiert, interessiert mich beispielsweise nicht. Daher gibt es ein paar Abfragen im PHP-Code, die solche “SMS-Send-Retry”-Infos ausfiltert und gar nicht bis an FileMaker durchstellt.
Kommentieren und Diskutieren