Skip To Content

Erstellen und Verwalten von Webhooks

Ein Webhook ist ein Mechanismus, der es einer Anwendung ermöglicht, für andere Anwendungen ereignisgesteuerte Informationen bereitzustellen. Als ArcGIS Enterprise-Portal-Administrator können Sie Webhooks erstellen, verwalten und konfigurieren. Sie können die Webhooks so konfigurieren, dass Sie automatisch benachrichtigt werden, wenn mit den Portalelementen, -gruppen und -benutzern verknüpfte Ereignisse eintreten. Nach dem Auslösen eines Webhooks erfolgt eine HTTP-Anforderung an eine eindeutige, benutzerdefinierte Payload-URL, um Informationen über das Ereignis bereitzustellen.

Wichtige Begriffe

Wichtige Begriffe im Zusammenhang mit Webhooks:

  • Trigger-Ereignis: Der von Ihnen festgelegte Vorgang zum Auslösen des Webhooks. Sie können z. B. festlegen, dass der Webhook ausgelöst wird, wenn eine bestimmte Gruppe in der Organisation aktualisiert wird oder wenn ein Element freigegeben wird. Für einen Webhook können mehrere Trigger-Ereignisse vorhanden sein.
  • Payload: Die Trigger-Ereignisdaten, die vom Webhook nach Eintreten des festgelegten Ereignisses übermittelt werden. Diese Informationen sind als JSON formatiert. Weitere Informationen finden Sie im nachfolgenden Abschnitt Payloads.
  • Payload-URL: Die Adresse, an die die Payload-Daten gesendet werden. Die Payload-URL kann mit einem Service wie z. B. Microsoft Power Automate, Zapier oder IFTTT erstellt werden. Sie können auch mit einer Plattform Ihrer Wahl einen eigenen benutzerdefinierten Web-Service-Endpunkt erstellen.

Beispielanwendungsfall

Webhooks ermöglichen die systemübergreifende Integration von Workflows, und es gibt viele Möglichkeiten für die Nutzung von Webhooks in Ihrer Organisation.

Überwachen der Aktivitäten in ArcGIS Enterprise

Ein Webhook kann zum Überwachen der Aktivitäten in ArcGIS Enterprise verwendet werden. Sie können beispielsweise alle Ereignisse abonnieren, die mit einem bestimmten Element verknüpft sind. Der Webhook wird ausgelöst, wenn die Eigenschaften des Elements aktualisiert werden, und mit einer HTTPS-Anforderung wird eine Payload übermittelt, die Daten enthält, die das Ereignis beschreiben. Sie legen fest, wohin die Payload übermittelt wird, und können bei Empfang der Informationen entsprechend handeln.

Unterstützte Trigger-Ereignisse

Beim Erstellen des Webhooks abonnieren Sie Trigger-Ereignisse. Da diese Ereignisse Portalvorgänge sind, muss in der Webhook-Konfiguration der URI des Vorgangs angegeben werden. In den folgenden Unterabschnitten werden die verfügbaren Trigger-Ereignisse und der zugehörige URI beschrieben.

Elemente

Die Elementeigenschaften, die aktualisiert werden können, variieren je nach Elementtyp, und der /update-Vorgang wird von eindeutigen Aktionen ausgelöst. Wenn das Element z. B. eine Webkarte ist, sind das Aktualisieren des Tags, das Konfigurieren eines Pop-ups und das Ändern der Grundkarte Aktualisierungsereignisse, die den Webhook auslösen.

In der folgenden Tabelle sind die Trigger-Ereignisse für unterstützte Portalelemente, die Webkarten, Web-Apps, Layer, Pakete, PDF-Dokumente usw. umfassen, aufgeführt:

Trigger-EreignisURI-Beispiel

Alle Trigger-Ereignisse für sämtliche Elemente

/items

Ein Element wird dem Portal hinzugefügt

/items/add

Ein Element wird gelöscht

/items/delete

Ein Element wird aktualisiert

/items/update

Ein Element wird verschoben oder der Besitzer ändert sich

/items/move

Ein Element wird veröffentlicht

/items/publish

Ein Element wird freigegeben

/items/share

Die Freigabe eines Elements wird aufgehoben

/items/unshare

Der Besitz eines Elements wurde neu zugewiesen

/items/reassign

Alle Trigger-Ereignisse für ein bestimmtes Element

/items/<itemID>

Ein bestimmtes Element wird gelöscht

/items/<itemID>/delete

Die Eigenschaften eines bestimmten Elements werden aktualisiert

/items/<itemID>/update

Der Besitzer eines bestimmten Elements ändert sich oder das Element wird verschoben

/items/<itemID>/move

Ein bestimmtes Element wird veröffentlicht

/items/<itemID>/publish

Ein bestimmtes Element wird freigegeben

/items/<itemID>/share

Die Freigabe eines bestimmten Elements wird aufgehoben

/items/<itemID>/unshare

Der Besitz eines bestimmten Elements wurde neu zugewiesen

/items/<itemID>/reassign

Gruppen

Alle allgemeinen Änderungen, die an den Gruppeneinstellungen vorgenommen werden, stellen eine Aktualisierung dar. Beispielsweise wird durch das Ändern des Zugriffs einer Gruppe ein Aktualisierungsereignis ausgelöst.

In der folgenden Tabelle sind die mit Gruppen verknüpften Trigger-Ereignisse aufgeführt:

Trigger-EreignisURI-Beispiel

Alle Trigger-Ereignisse für sämtliche Gruppen

/groups

Eine Gruppe wird hinzugefügt

/groups/add

Eine Gruppe wird aktualisiert

/groups/update

Eine Gruppe wird gelöscht

/groups/delete

Löschschutz wird für eine Gruppe aktiviert

/groups/protect

Löschschutz wird für eine Gruppe deaktiviert

/groups/unprotect

Ein Benutzer wird in eine Gruppe eingeladen

/groups/invite

Ein Benutzer wird einer Gruppe hinzugefügt

/groups/addUsers

Ein Benutzer wird aus einer Gruppe entfernt

/groups/removeUsers

Die Rolle eines Benutzers in einer Gruppe wird aktualisiert

/groups/updateUsers

Der Besitz einer Gruppe wurde neu zugewiesen

/groups/reassign

Alle Trigger-Ereignisse für eine bestimmte Gruppe

/groups/<groupID>

Eine bestimmte Gruppe wird aktualisiert

/groups/<groupID>/update

Eine bestimmte Gruppe wird gelöscht

/groups/<groupID>/delete

Löschschutz wird für eine bestimmte Gruppe aktiviert

/groups/<groupID>/protect

Löschschutz wird für eine bestimmte Gruppe deaktiviert

/groups/<groupID>/unprotect

Ein Benutzer wird in eine bestimmte Gruppe eingeladen

/groups/<groupID>/invite

Ein Benutzer wird einer bestimmten Gruppe hinzugefügt

/groups/<groupID>/addUsers

Ein Benutzer wird aus einer bestimmten Gruppe entfernt

/groups/<groupID>/removeUsers

Die Rolle eines Benutzers in einer bestimmten Gruppe wird aktualisiert.

/groups/<groupID>/updateUsers

Der Besitz einer bestimmten Gruppe wurde neu zugewiesen

/groups/<groupID>/reassign

Benutzer

Bei jeder Änderung am Profil des Benutzers wird ein Aktualisierungsereignis ausgelöst. Änderungen an der Rolle, am Benutzertyp oder der Lizenz eines Benutzers gelten jedoch nicht als Aktualisierung des Benutzerprofils.

In der folgenden Tabelle sind die mit Benutzern verknüpften Trigger-Ereignisse aufgeführt:

Trigger-EreignisURI-Beispiel

Alle Trigger-Ereignisse für sämtliche Benutzer im Portal

/users

Ein Benutzer wird der Organisation hinzugefügt

/users/add

Ein Benutzer hat sich beim Portal angemeldet.

/users/signin

Ein Benutzer hat sich beim Portal abgemeldet

/users/signout

Ein Benutzer wird gelöscht

/users/delete

Ein Benutzerprofil wird aktualisiert

/users/update

Ein Benutzerkonto wird deaktiviert

/users/disable

Ein Benutzerkonto wird aktiviert

/users/enable

Einem Benutzer wurde eine neue Rolle zugewiesen

/users/updateUserRole

Einem Benutzer wurde ein neuer Benutzertyp zugewiesen

/users/updateUserLicenseType

Alle Trigger-Ereignisse, die mit einem bestimmten Benutzer verknüpft sind

/users/<username>

Ein bestimmter Benutzer ist beim Portal angemeldet

/users/<username>/signIn

Ein bestimmter Benutzer ist beim Portal abgemeldet

/users/<username>/signOut

Ein bestimmter Benutzer wird gelöscht

/users/<username>/delete

Ein bestimmtes Benutzerprofil wird aktualisiert

/users/<username>/update

Ein bestimmtes Benutzerkonto wird deaktiviert

/users/<username>/disable

Ein bestimmtes Benutzerkonto wird aktiviert

/users/<username>/enable

Einem bestimmten Benutzer wurde eine neue Rolle zugewiesen

/users/<username>/updateUserRole

Einem bestimmten Benutzer wurde ein neuer Benutzertyp zugewiesen

/users/<username>/updateUserLicenseType

Rollen

Bei jeder Änderung an den Rollen in Ihrer Organisation wird ein Aktualisierungsereignis ausgelöst.

In der folgenden Tabelle sind die mit Benutzerrollen verknüpften Trigger-Ereignisse aufgeführt:

Trigger-EreignisURI-Beispiel

Alle Trigger-Ereignisse für sämtliche Rollen im Portal

/roles

Eine neue Rolle wird erstellt

/roles/add

Eine vorhandene Rolle wird aktualisiert

/roles/updated

Eine vorhandene Rolle wird gelöscht

/roles/delete

Payloads

Nach dem Auslösen eines Webhooks wird eine Payload im JSON-Format an die betreffende Payload-URL übermittelt. Jedes Ereignis weist ein ähnliches JSON-Schema mit für das Ereignis relevanten Informationen auf.

SchlüsselTypBeschreibung
webhookName

string

Der Name des Webhooks, von dem die Payload übermittelt wurde

webhookId

string

Die ID des Webhooks, von dem die Payload übermittelt wurde

portalURL

string

Die URL des Portals, bei dem der Webhook registriert ist

when

timestamp

Der Zeitpunkt, zu dem die Payload übermittelt wurde

username

string

Der Benutzer, der das Ereignis ausgelöst hat

userId

string

Die ID des Benutzers, der das Ereignis ausgelöst hat

when

timestamp

Der Zeitpunkt, zu dem das Ereignis eingetreten ist

operation

string

Der vom Benutzer ausgeführte Vorgang. Dies kann Folgendes sein:

  • add
  • addUsers
  • delete
  • disable
  • enable
  • invite
  • move
  • protect
  • publish
  • removeUsers
  • share
  • unprotect
  • unshare
  • update
  • updateUsers
source

string

Der Elementtyp, für den der Vorgang ausgeführt wurde. Hierbei kann es sich um item, group oder user handeln.

id

string

Die ID des Quellelements, für das der Vorgang ausgeführt wurde.

properties

object

Zusätzliche mit dem Ereignis verknüpfte Eigenschaften. Dies kann Folgendes sein:

  • sharedToGroups: Wie ein Element freigegeben wird (groupID, Organization oder Everyone)
  • unsharedFromGroups: Wie die Freigabe eines Elements aufgehoben wird (groupID, Organization oder Everyone)
  • removeUserNames: Die Benutzernamen der aus einer Gruppe entfernten Benutzer.
  • updateUserNames: Die Benutzernamen der Benutzer, deren Gruppenrollen aktualisiert wurden.
  • invitedUserNames: Die Benutzernamen der zu einer Gruppe eingeladenen Benutzer.
  • addedUserNames: Die Benutzernamen der einer Gruppe hinzugefügten Benutzer
  • userRoleUpdatedTo: Die neue Rolle, die dem Benutzer zugewiesen wurde.
  • reassignedTo: Der neue Benutzer, dem ein Element oder eine Gruppe neu zugewiesen wurde.
  • userLicenseTypeUpdatedTo: Der neue Benutzertyp, der einem Benutzer zugewiesen wurde.
  • name: Der Name der Rolle, die erstellt, aktualisiert oder gelöscht wurde.

Nutzdaten-URL

Beim Erstellen eines Webhooks muss der Benutzer eine Payload-URL angeben. Diese definiert, wohin die Payload übermittelt wird. Da die Payload über eine HTTPS-POST-Anforderung übermittelt wird, muss der Webhook-Empfänger für die Kommunikation über HTTPS konfiguriert und durch das Portal erreichbar sein. Sie können mehrere Web-Services, z. B. Microsoft Power Automate, Zapier und IFFT, verwenden, um mit der Payload benutzerdefinierte Workflows zu konfigurieren. Beispielsweise können Sie einen Workflow erstellen, mit dem bei Empfang einer Payload durch Microsoft Power Automate die Payload geparst, formatiert und an einen E-Mail-Alias gesendet wird. Alternativ können Sie den Web-Service erstellen und für den Empfang von Payloads anpassen. Für Organisationen, die den Internetzugang beschränken, wird das Erstellen eines benutzerdefinierten Web-Service für den Empfang von Payloads empfohlen. Ein sofort einsatzfähiges Java-Servlet finden Sie in unseren Enterprise SDK-Beispielen.

Payload-Beispiel

Im folgenden Beispiel-Payload wird angegeben, dass eine bestimmte Gruppe aktualisiert wurde:


{
   "info": {
      "webhookName": "Group monitoring",
      "webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
      "portalURL": "https://orgURL/portal/",
      "when": 1543192196521
   },
   "events": [{
      "username": "administrator",
      "userId": "173dd04b69134bdf99c5000aad0b6298",
      "when": 1543192196521,
      "operation": "update",
      "source": "group",
      "id": "173dd04b69134bdf99c5000aad0b6298",
      "properties": {}
   }]
}

Erstellen eines Webhooks

Webhooks können nur über das ArcGIS-Portalverzeichnis (Freigabe-API) verwaltet werden. Führen Sie zum Erstellen eines Webhooks die folgenden Schritte aus:

  1. Navigieren Sie zum ArcGIS-Portalverzeichnis.
    https://machine.domain.com/webadaptor/sharing/rest
  2. Melden Sie sich als Administrator an.

    Webhooks können nur von Administratoren erstellt und verwaltet werden.

    Die Benutzerseite des Administrators wird angezeigt.

  3. Klicken Sie auf den Hyperlink Org ID, oder erstellen Sie eine Anforderung im unten gezeigten Format, um zur Ressourcenseite "Portal Self" zu gelangen.
    https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
  4. Führen Sie einen Bildlauf zum unteren Bereich der Seite durch, zu Webhooks unter Untergeordnete Ressourcen.
    https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
  5. Wählen Sie unter Supported Operation Create Webhook aus.
  6. Geben Sie die Parameter für den Webhook an.

    Informationen über diese Parameter finden Sie in der REST-API-Dokumentation des Webhooks.

    Ihr Webhook ist jetzt in der Liste "webhooks" enthalten: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks

Verwalten von Webhooks

Sie können die Webhooks über das ArcGIS-Portalverzeichnis verwalten, indem Sie eine Anforderung im folgenden Format erstellen:

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.

Die folgenden Vorgänge zum Verwalten von Webhooks werden unterstützt:

  • Update Webhook: Aktualisieren der Parameter des Webhooks. Sie können den Namen, die Payload-URL, die Konfiguration und die Trigger-Ereignisse für den angegebenen Webhook aktualisieren.
  • Delete Webhook: Entfernen des Webhooks aus dem Portal.
  • Deactivate Webhook und Activate Webhook: Deaktivieren des Webhooks. Hierdurch werden beim Auslösen des Webhooks keine Payloads mehr übermittelt. Wenn der Webhook deaktiviert ist, kann mit dem Vorgang "Activate Webhook" die Übermittlung von Webhooks wieder aufgenommen werden.

Auf der Seite Notification Status werden Informationen über Trigger-Ereignisse für den betreffenden Webhook angezeigt. Sie können mithilfe dieser Tabelle den Webhook sowie Informationen über übermittelte Payloads, z. B. den Zeitpunkt des Auslösens des Webhooks, die über die Payload-URL empfangenen Antworten und die übermittelte Payload, anzeigen. Einträge, in denen die erfolgreiche Übermittlung einer Payload angegeben wird, werden nach einem Tag entfernt. Einträge, die eine fehlgeschlagene Übermittlung angeben, werden sieben Tage lang gespeichert.

Beispiele für diese Vorgänge finden Sie in der Webhooks-API.

Konfigurieren erweiterter Parameter

Es gibt mehrere erweiterte Parameter, mit denen die Webhooks weiter angepasst werden können. Diese Parameter werden auf alle konfigurierten Webhooks im Portal angewendet, und der Zugriff auf sie erfolgt über https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings..

Mit dem Vorgang Update können Sie die folgenden Parameter aktualisieren:

  • Number of delivery attempts: Geben Sie die Anzahl der Versuche zum Übermitteln einer Payload an. Standardmäßig erfolgen drei Versuche. Diese Anzahl kann auf bis zu fünf Versuche erhöht werden.
  • Notification timeout: Geben Sie an, wie lange eine Verbindung auf den Empfang einer Antwort wartet. Wenn in diesem Intervall keine Antwort empfangen wird, erfolgt ein Timeout der Verbindung, und die Benachrichtigung gilt als fehlgeschlagen.
  • Elapsed time between delivery attempts: Geben Sie die Zeit zwischen den einzelnen Versuchen der Payload-Übermittlung an. Der Standardwert ist 30 Sekunden. Er kann auf maximal 100 Sekunden erhöht oder auf bis zu 1 Sekunde verringert werden.

Weitere Informationen zum Konfigurieren erweiterter Parameter finden Sie in der Webhooks-API-Dokumentation.

Häufig gestellte Fragen zu Webhooks

Die folgenden Fragen werden bei der Verwendung von Webhooks häufig gestellt.

ArcGIS Enterprise wird in einer nicht verbundenen Umgebung hinter der Firewall meiner Organisation bereitgestellt. Kann ich trotzdem Webhooks konfigurieren?

Ja. Um Webhooks zu konfigurieren, müssen Sie eine Payload-URL verwenden, die über Ihr ArcGIS Enterprise-Portal erreichbar ist. Dazu können Sie eine benutzerdefinierte Anwendung und auf Ihrem internen Server bereitstellen.

Was löst eine Aktualisierung eines Elements, eines Benutzers oder einer Gruppe aus?

Wenn Sie Aktualisierungen für Ihre Portal-Elemente, Benutzer und Gruppen abonniert haben, wird Ihr Webhook ausgelöst, wenn deren Eigenschaften aktualisiert wurden. Wenn Sie beispielsweise Aktualisierungen für ein bestimmtes Element in Ihrem Portal abonniert haben, wird Ihr Webhook ausgelöst, sobald der Titel, die Tags oder die Miniaturansicht des Elements aktualisiert wurden. Der Netzwerkverkehr bietet Aufschluss darüber, ob eine Aktion eine Aktualisierung im Portal bewirkt. Jedes Mal, wenn eine Aktion zu einer Aktualisierung führt, kann diese Aktion auch einen Webhook auslösen, der auf Aktualisierungen wartet.

Ich verwende die integrierte Windows-Authentifizierung in meinem ArcGIS Enterprise-Portal. Kann ich trotzdem die An- und Abmeldung von Benutzern im bzw. aus dem Portal abonnieren (user/<username>/signIn)?

Ab Version 10.9 können Sie mit dem Trigger-Ereignis /signin Anmeldeereignisse für die Portal-Authentifizierung, die Authentifizierung auf Webebene und für Enterprise-Anmeldenamen erfassen.

Was passiert, wenn meine Payload-URL ausfällt oder nicht mehr verfügbar ist? Gibt es eine Möglichkeit, eine Payload wiederherzustellen, die nicht übermittelt wurde?

Wenn das Portal versucht, eine Payload an einen nicht erreichbaren oder nicht reagierenden Payload-URL- oder Webhook-Empfänger zu übermitteln, bestimmen die von Ihnen festgelegten erweiterten Parameter, wie und wann ein neuer Versuch unternommen wird. Wenn die Payload auch nach weiteren Versuchen nicht übermittelt wird, gilt dies als ein Fehler im Hinblick auf die beim Erstellen des Webhooks festgelegten deactivationPolicy. Der Webhook wird deaktiviert, sobald diese Richtlinie erfüllt ist.

Sie können zum Benachrichtigungsstatus des Webhooks wechseln, um alle Payload-Übermittlungsversuche anzuzeigen und herauszufinden, ob diese erfolgreich waren.