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.

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.

//groupIDs
"properties": {
  "sharedToGroups": [
    "ecd6646698b24180904e4888d5eaede3",
    "2dff15c514ad4f04b291e304e24a524b"
  ]
}

//Everyone and groupIDs
"properties": {
  "sharedToGroups": [
    "Everyone",
    "4adc30bb03054812a846fa592de105de",
    "a4e6e37e2f7d4bb5b64d587c91d39a2c"
  ]
}

//Everyone
"properties": {
  "unsharedFromGroups": ["Everyone"]
}

//groupID
"properties": {
  "unsharedFromGroups": [
    "4adc30bb03054812a846fa592de105de"
  ]
}

"properties": {
  "invitedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "addedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "removedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "updatedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "sharedItems": [
    {
      "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1",
      "itemType": "Map Package"
    }
  ]
}

"properties": {
  "unsharedItems": [
    {
      "itemId": "7dd95fadaec84859ab8ed1059e675e0c",
      "itemType": "Image"
    }
  ]
}

"properties": {
  "userRoleUpdatedTo": ["New role"]
}

"properties": {
  "userLicenseTypeUpdatedTo": ["Editor"]
}

"properties": {
  "name": ["New role"]
}

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.

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.

{
  "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

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.