Die WebHook Integration App ermöglicht es der DataEngine, WebHooks von externen Systemen zu empfangen und in Echtzeit auf Ereignisse zu reagieren. Dadurch können Daten von verschiedenen Plattformen automatisch in die MARINI Plattform integriert werden, ohne manuelle Eingriffe. Dies erleichtert die Automatisierung von Prozessen und die Verbindung von Drittanbieter-Tools mit der Plattform. Die App kann flexibel konfiguriert werden, um eine Vielzahl von WebHooks und Integrationsmöglichkeiten zu unterstützen.
Installation und Einrichtung der WebHook Integration
Um die Webhook App zu verwenden, führe die folgenden Schritte aus:
- Installiere die „Webhook Integration“-App. Gehe dazu in den Admin Bereich deiner DataEngine und wähle unter Entwickler Werkzeuge „Erweiterungen verwalten“ aus.
- Suche die App in der Liste der installierbaren Erweiterungen aus dem Marini Store und lade diese herunter.
- Installiere diese App anschließend, indem du auf den „Installieren“-Button in der Liste der installationsbereiten Erweiterungen klickst.
- Erstelle ein Modul (oder verwende ein bereits existierendes Modul) in der DataEngine, welches die Daten der Webhook-Integration empfangen soll. Damit das Modul die Daten der Webhook-Integration problemlos empfangen kann, müssen folgende Felder verpflichtend vorhanden sein:
rawjson: Dieses Feld enthält den Inhalt der Anfrage als JSON-String.path: Dieses Feld enthält den Pfadteil (denxxx/xxx-Teil) aus dem POST-Request.
Wenn du im Vorfeld weißt, wie die Felder im JSON Request abgebildet werden, kannst du die Feldnamen im Modul so vergeben. Die JSON-Datei wird anschließend automatisch durchsucht und der Inhalt in die entsprechenden Felder übertragen. Dabei gelten folgende Regeln:
- Zum Beispiel wird das JSON
{"EventType":"aaa"}in das FeldEventTypegeschrieben, wenn es existiert. - Wenn das JSON Objekte/Arrays enthält, können diese mit einem Unterstrich im Feldnamen angesprochen werden. Zum Beispiel kann
{"Properties":{"ClientId":"aaa"}}über den Feldnamenproperties_clientidauf"aaa"gesetzt werden. - Ein Feld namens
propertieshingegen kann den kompletten JSON-String erhalten, z.B.{"ClientId":"aaa"}. - Die Feldnamen im Datensatz können in beliebiger Groß- und Kleinschreibung vorliegen. Auch benutzerdefinierte Felder werden überprüft, sodass beispielsweise auch die Zuordnung zu
properties_ClientId_cfunktioniert. - Benutzerdefinierte Konfigurationen können über die Custom Config für lange Feldnamen verwendet werden. Dazu muss ein gesondertes Mapping in der Custom Config angelegt werden. Die Anleitung hierzu findest du hier: https://marini.systems/de/help-center/docs/custom-config/#Webhook
- Enthält ein Post-Request mehrere Datensätze (komma-separiertes JSON), ist eine automatische Zuordnung anhand der Felder nicht möglich. Hierzu müssen die Daten dann mittels Workflow Action JSON Split in jeweils eigene Datensätze aufgeteilt werden.
Einrichtung der Zugangsdaten
Um den bearer-Token für den Zugriff zu generieren, musst du folgende Schritte befolgen:
- Lege über das User Management zunächst einen gesonderten Nutzer an, über den die Autorisierung erfolgen soll.
- Logge dich einmalig mit diesem User ein und vergebe ein neues Passwort.
- Speichere dir die User-ID des Nutzers in der Zwischenablage, diese findest du in der URL deiner DataEngine, wenn du dich auf dem Datensatz des Nutzers befindest und wird später für die Einrichtung des Tokens benötigt. Die URL sieht bspw. so aus
https://<your-dataengine-instance>/index.php?module=Users&return_module=Users&action=DetailView&record=aff3e2d5-f063-025c-c7d3-6735d88b2aebund du findest die ID am Ende der URL (fett markiert). - Identifiziere den Modul-Namen des Moduls, das die Daten über die Webhook Integration empfangen soll. Diesen Namen findest du ebenfalls über die URL, wenn du über das Menü auf dieses Modul klickst. Die URL sieht bspw. so aus
https://<your-dataengine-instance>/index.php?module=Webhook_Integrationund du findest den Modul-Namen hinter dem Parametermodule(fett markiert). - Um einen Zugrisstoken (Access Token) zu erhalten musst du folgende Seite besuchen:
https://<your-dataengine-instance>/index.php?entryPoint=WebhookTokenAlternativ findest du im Admin-Bereich unter Externe Services den Punkt „Webhook Access Token“. - Gebe in der Maske die oben gespeichert User ID, sowie den Modul-Namen ein und klicke anschließend auf „Generate“.
- Speichere den angezeigten Token und ggf. auch die Signatur in einer Passwort-Verwaltungs-App. Diese sind nur einmalig sichtbar.
Wie kann das Modul Daten per Webhook empfangen?
Der Sender (Absender) des Webhooks kann POST-Anfragen an folgende URL senden:
https://<your-dataengine-instance>/entrypoint/WebhookODERhttps://<your-dataengine-instance>/entrypoint/Webhook/xxx/xxx(wobeixxx/xxxgenutzt werden kann, um Variablen mitzugeben, bspw. um unterschiedliche Quellen zu identifizieren)
Folgender Header muss in der POST-Anfrage verwendet werden:
- Content-Type: application/json
- Authorization: Bearer
<Access Token>(ersetze<Access Token>durch deinen erhaltenen Zugriffstoken) - X-Signature (optional):
<HMAC-Hash des Inhalts>
Der Webhook wird immer einen neuen Datensatz in der DataEngine erstellen. Dabei wird der Datensatz von dem Benutzer erstellt, der beim Erstellen des Zugriffstokens definiert wurde. Der Datensatz wird in dem Modul angelegt, welches bei der Vergabe des Tokens hinterlegt wurde. Die Felder des Datensatzes werden gemäß der oben beschriebenen Regeln gefüllt.
Durch die Verwendung der DataEngine WebHook Integration App kannst du problemlos Daten aus externen Diensten in die DataEngine integrieren und so die Effizienz deiner Datenverarbeitung steigern.
Unsere Tipps und Empfehlungen:
- Überlege dir, ob du für das Modul, dass die Webhook Daten empfängt, ein Löschkonzept überlegst. Die Daten werden nach der einmaligen Verarbeitung meist nicht mehr benötigt und können bereinigt werden. Das hilft dir bei einem effizienten Datenbank-Management
- Nutze für Integrationen vorwiegend die HubEngine. Als iPaas Lösung ist sie unsere Komponente für nahtlose Integrationen. Eine Übersicht möglicher Integrationen findest du hier. Die Webhook Integration dient als Alternative, falls es keine andere Möglichkeit der Integration gibt.