Mit den Webhooks für Hosted Features Services steht ein wirkungsvolles Werkzeug zur Verfügung, um Aufgaben zu automatisieren und Aktionen in ArcGIS mit anderen Systemen zu verknüpfen.
In diesem Blogartikel werden die Grundlagen für die Einrichtung von Webhooks auf Hosted Feature Services erklärt. Sowohl ArcGIS Online als auch ArcGIS Enterprise (ab Version 11.1) unterstützen die Einrichtung. Heute konzentrieren wir uns auf die Konfiguration mit ArcGIS Online.
Was sind Webhooks?
Ein Webhook (Wikipedia zu Webhooks) ermöglicht es Webdiensten, anderen Diensten mit Hilfe von HTTP-POST-Anfragen Informationen nahezu in Echtzeit zu liefern. Webhooks sind benutzerdefinierte HTTP-Callbacks, die in der Regel durch ein Event/Ereignis ausgelöst werden, wie z. B. das Bearbeiten oder Synchronisieren eines Features oder das Hinzufügen von Bildern zu Features. Wenn dieses Ereignis eintritt, stellt die konfigurierte Quelle, z. B. ein gehosteter Feature-Dienst, eine HTTP-Anforderung an die für den Webhook konfigurierte URL.
Ein Beispiel: Mit einem ArcGIS Survey123 Formular wird von einer/m Außendienstmitarbeiter:in ein neuer Datensatz für einen Unwetterschaden erfasst. Sobald die Daten komplett gespeichert sind, wird eine Nachricht an den Innendienst geschickt, der dann diese Daten nehmen und den Fall mit weiteren Tools bearbeiten kann.
Durch Webhooks muss eine weiterverarbeitende Stelle oder ein System nicht regelmäßig nachsehen, ob es neue oder geänderte Daten gibt („pull“). Stattdessen wird eine Aktion ausgelöst („push“), sobald es Änderungen gibt .
Ereignis/Event
Die Basis von Webhooks sind Events. Ein Webhook wird durch einen definierten Event ausgelöst. Bei der Konfiguration eines Webhooks können ein oder mehrere Ereignisse definiert werden.
Beispiel
- FeaturesCreated -> Ein neues Feature wurde erzeugt.
- AttachmentsCreated -> Ein neues Attachement (z.B. Bild) wurde einem Feature hinzugefügt.
Eine komplette Übersicht aller Events gibt es in der Developer Hilfe Trigger-Events.
Payload
Jeder Event hat einen bestimmten Payload, der mitgeschickt wird. In der Payload sind Informationen über den Typ und den Service enthalten, sowie URLs, über die weitere Informationen abgerufen werden können.
Der Event ‚FeaturesCreated‘ erzeugt beispielsweise eine solche Payload:
Mit der Angabe unter „changesURL“ können weitere Details abgefragt werden (nicht mehr Teil dieses Blogbeitrags).
In der Entwicklerhilfe gibt es eine komplette Liste der Event Payloads.
Webhook Integration
Wenn in einem Hosted Feature Service durch einen Event eine Payload verschickt wird, muss ein anderes System diese Webhooks empfangen („Receiver“). Das können die unterschiedlichsten Systeme sein, auch eigene interne. Es gibt Unternehmen, die eine solche Integrationsumgebung als Dienst anbieten, z. B. Microsoft Power Automate oder Make (ehemals Integromat).
Für diesen Blogbeitrag nutze ich als Beispiel einen kostenlosen Account bei Make.
Die Schritte und Möglichkeiten der Webhook Integration unterscheiden sich im Detail bei den verschiedenen Anbietern. Aber das Prinzip ist gleich.
Beispiel für Webhook-Definition und Verarbeitung
Zur Veranschaulichung wird ein Beispiel mit einer Schritt-für-Schritt-Anleitung für einen Hosted Feature Service auf ArcGIS Online und der Integrationsplattform Make gegeben.
Falls Sie keine der beiden Umgebungen haben: Für ArcGIS Online gibt es ein kostenloses, dreiwöchiges Trial und für Make einen funktional eingeschränkten Free Plan, der zum Testen und Ausprobieren ausreicht. Oder schauen Sie gerne in unserem Esri Store vorbei:
Ich gehe im Folgenden nicht weiter auf die grundlegende Bedienung von ArcGIS Online ein oder wie man überhaupt einen Hosted Feature Service anlegt. Sie sollten also schon ein wenig Erfahrung mit ArcGIS haben, wenn Sie das folgende Beispiel konfigurieren möchten.
Tipp: Falls Sie noch keine ArcGIS-Kenntnisse haben, sollten Sie zuerst mit diesem Lernprogramm starten.
Szenario “E-Auto-Ladestationen”
Mit einem ArcGIS Survey123 Formular können Bedarfe für E-Auto-Ladestationen gemeldet werden. Jedes Mal, wenn ein neuer Bedarf gemeldet wird, bekommt ein:e Sachbearbeiter:in eine E-Mail.
Das Beispiel unten ist generisch gestaltet, damit es für jeden Feature Service und für jede App funktioniert.
Voraussetzungen
- Sie sind entweder Administrator:in in der ArcGIS Online Subskription oder Eigentümer:in des Hosted Feature Service.
- Der Feature Service muss die Eigenschaften ‚Bearbeitung aktivieren‘ und ‚Verfolgen Sie Änderungen an den Daten (hinzugefügte, aktualisierte, gelöschte Features)‘ aktiviert haben.
Schritt 1: Einen Webhook definieren
Webhooks werden über ein REST-Interface erzeugt. Es gibt momentan kein graphisches User Interface.
- In der ‚Übersicht‘-Seite des Hosted Feature Layer öffnen Sie die URL des Dienstes. Sie finden die URL rechts unten. Klicken Sie dabei auf ‚Anzeigen‘:
- Da das Definieren von Webhooks einen autorisierten Zugriff auf den Dienst benötigt, müssen Sie sich immer anmelden bzw. einen Token mitnehmen.
Kleiner Trick: Auf der Seite, die nach ‚Anzeigen‘ erscheint, einen Rechtsklick auf den Namen des Service tätigen (hier: > Bedarfsabrage_2_ (FeatureServer)) und in einem neuen Tab öffnen. Dann wird der Token für die Autorisierung gleich mitgenommen.
Auf der neu erscheinenden Seite klicken Sie auf ‚Admin‘, um von der Abfrage- in die Administrationsumgebung zu gelangen.
Im Browserfenster sieht es dann so aus:
- Die URL im Browser sieht wie folgt aus:
…./FeatureServer?token=….
Jetzt ergänzen Sie mit:
…./FeatureServer/WebHooks/create?token=….
- Im nun erscheinenden Fenster können schließlich die Webhooks definiert werden. Der Weg dorthin ist etwas umständlich, aber es lohnt sich. Eine UI wird in einem der nächsten Releases hinzugefügt.
Die Seite sieht wie folgt aus und muss noch um einige Einträge erweitert werden:
Eine komplette Beschreibung der Parameter gibt es hier: WebHook Request Parameter
Für unseren Zweck reichen aber diese Angaben:
- Name: Bedarf_Benachrichtigung -> Der Name des Webhooks.
- Change Types: [“FeaturesDeleted”, “FeaturesCreated”, “FeaturesUpdated”] -> Wir wollen über alle Änderungen benachrichtigt werden.
- HookUrl: https://www.esri.de -> Das ist momentan noch ein Platzhalter für den/die Empfänger:in der Payload. Die Einrichtung erfolgt im nächsten Schritt.
Nun auf „Create“ klicken und der Webhook ist definiert. Es erscheint diese Zusammenfassung:
Hinweis: Diese Seite geöffnet lassen; wir werden sie noch brauchen.
Schritt 2: Den Webhook mit Make integrieren
Wie schon erwähnt, kann die Integration mit unterschiedlichen Lösungen erfolgen. Beispielhaft mache ich sie in diesem Beispiel mit Make:
- Melden Sie sich in Make an.
- Klicken Sie auf Create a new scenario:
- Weiter auf das große + Symbol klicken:
- Und nach Webhooks suchen:
- Wählen Sie nun das “Custom webhook” Modul an:
- Nun auf ‘Create a webhook’ klicken, Name vergeben und ‚Save‘ klicken:
- Jetzt wartet der Prozess auf den ersten Input. Kopieren Sie dafür die angegebene URL (hier: https://hook.eu1.make.com/y9……
- Gehen Sie nun zurück in ArcGIS Online auf den vorher definierten Webhook und klicken dort auf ,Edit´.
- Nun die kopierte URL unter ,HookUrl´ eintragen und den Edit-Button klicken:
- Jetzt ist der Webhook mit dem Make Prozess verbunden. An dieser Stelle wartet Make mit dem definierten Prozess noch darauf, dass etwas geschickt wird.
- Als nächstes wird eine Aktion im Map Viewer ausgeführt. Z. B. wird ein Feature erzeugt, damit eine erste Payload zu Make geschickt und der wartende Prozess dort ebenfalls abgeschlossen wird. Das Einlesen einer ersten Payload können Sie zu einem späteren Zeitpunkt wiederholen.
Sobald Daten angekommen sind, kann die Struktur ermittelt werden und die wichtigsten Schritte sind abgeschlossen.
Herzlichen Glückwunsch! Der erste Webhook ist erstellt und es werden Informationen versendet.
Schritt 3: Aktionen in Make ausführen
Jetzt können Sie in Make weitere Verarbeitungsschritte ausführen. Der Einfachheit halber wollen wir in diesem Fall jedes Mal, wenn der Webhook getriggert wird, eine E-Mail (an mich selber) versenden.
- Dafür gehen wir in Make zurück in das Szenario und klicken im bestehenden Szenario auf + Add another module:
- Wir suchen nach Outlook, wählen Microsoft 365 Email und die Aktion Create and Send a Message aus:
- Im folgenden Fenster werden die notwendigen Parameter für das Versenden der E-Mail eintragen. Wenn Sie nicht Office 365 für E-Mails nutzen, können Sie auch ein Modul für einen anderen Provider wählen (z. B. Gmail):
Ich habe hier die folgende Parameter gewählt:
Connection: Verbindung zu meinem E-Mail-Provider
Subject: Ein sprechender Text
Body Content: payload (In den Text der E-Mail kommt die Nachricht, die vom Webhook auf ArcGIS Online versendet wird.)
Empfänger: mich = Jörg Moosmeier
- Nun kann es schon los gehen. Wenn sich im Feature Service etwas tut, wird ein Webhook ausgelöst. Dieser sendet eine Payload an einen Receiver und dann eine E-Mail.
In meinem Fall sieht diese E-Mail wie folgt aus:
Allein mit diesen Informationen in der E-Mail kann man recht wenig anfangen. Durch die URL können Sie aber auf weitere Details zugreifen.
In einem operativen Szenario würden Sie in Make mit der empfangenen Payload erst die changesURL auslesen, dann mit der URL den Service abfragen, die notwendigen Attribute extrahieren und dann weitere Aktionen unternehmen.
Welche Aktionen das sein könnten, hängt natürlich vom Workflow ab und den Möglichkeiten der Intergrationsplattform. Z. B.:
- Kommunikationsautomatisierung: Nachrichten an Ersteller:in bei Veränderungen; Benachrichtigung an eine:n Sachbearbeiter:in
- Erzeugung eines ToDos oder eines Eintrags in einem CRM
- Erzeugung eines Datensatzes in einer externen Datenbank
- Ansteuern eines Python-Skriptes zur Sicherung von Datenqualität
- Aktualisierung von Informationen auf einer Webseite oder einem CMS
Wie das weitere Arbeiten mit der changesURL aussieht, ist nicht mehr Teil dieses Beitrags, sondern für einen folgenden Beitrag eingeplant.
Weitere Informationen finden Sie im Blogbeitrag ,Create a hosted feature service webhook´ unserer amerikanischen Kolleg:innen, der diesen Beitrag inspiriert hat.
