Skip To Content

Créer et gérer des webhooks

Un webhook est un mécanisme qui permet à une application de fournir à d’autres applications des informations liées aux événements. En tant qu’administrateur du portail ArcGIS Enterprise, vous pouvez créer, gérer et configurer des webhooks. Vous pouvez configurer vos webhooks pour qu’ils vous avertissent automatiquement lorsque des événements associés à vos éléments de portail, groupes et utilisateurs surviennent. Lorsqu’un webhook est déclenché, une requête HTTP est adressée à une payload URL définie par l’utilisateur unique pour qu’elle fournisse des informations concernant l’événement.

Termes clés

Voici les termes clés associés aux webhooks :

  • Événement déclencheur : l’opération définie qui doit déclencher votre webhook. Vous pouvez par exemple configurer le déclenchement de votre webhook lorsqu’un groupe donné est mis à jour dans votre organisation ou lorsqu’un élément est partagé. Un webhook peut comporter plusieurs événements déclencheurs.
  • Payload : les données de l’événement déclencheur livrées par votre webhook une fois que l’événement spécifié a eu lieu. Ces informations sont au format JSON. Consultez la section Payloads ci-dessous pour plus d’informations.
  • Payload URL : l’emplacement où sera envoyé la payload. La payload URL peut être créée à l’aide d’un service, tel que Microsoft Power Automate, Zapier ou IFTTT. Vous pouvez également créer votre propre extrémité du service web personnalisé à l’aide d’une plate-forme de votre choix.

Exemple de cas d’utilisation

Les webhooks permettent d’intégrer des processus dans les systèmes. Vous pouvez tirer parti des webhooks de plusieurs manières dans votre organisation.

Surveiller l’activité dans ArcGIS Enterprise

Un webhook peut servir à surveiller l’activité dans ArcGIS Enterprise. Vous pouvez par exemple vous abonner à tous les événements associés à un élément en particulier. Le webhook est déclenché lorsque les propriétés de l’élément sont mises à jour et une requête HTTPS livre une payload qui contient les données décrivant l’événement. Vous choisissez le lieu de livraison de cette payload et pouvez agir comme il convient lorsque vous recevez les informations.

Événements déclencheurs pris en charge

Lorsque vous créez votre webhook, vous vous abonnez aux événements déclencheurs. Comme ces événements sont des opérations du portail, l’URI de l’opération doit être spécifiée dans la configuration du webhook. Les sous-sections ci-dessous décrivent les événements déclencheurs disponibles et l’URI associée.

Eléments

Les propriétés d’élément pouvant être mises à jour varient selon les types d’élément et des actions uniques déclenchent l’opération /update. Par exemple, si l’élément est une carte web, la mise à jour de la balise, la configuration d’une fenêtre contextuelle ou le changement de fond de carte sont tous des événements de mise à jour qui déclencheront le webhook.

La table suivante répertorie les événements déclencheurs pour les éléments de portail pris en charge, dont notamment les cartes web, les applications web, les couches, les paquetages, les documents PDF :

Événement déclencheurExemple d’URI

Tous les événements déclencheurs pour tous les éléments

/items

Un élément est ajouté au portail

/items/add

N’importe quel élément est supprimé

/items/delete

N’importe quel élément est mis à jour

/items/update

N’importe quel élément est déplacé ou son appartenance modifiée

/items/move

N’importe quel élément est publié

/items/publish

N’importe quel élément est partagé

/items/share

Le partage de n’importe quel élément est annulé

/items/unshare

La propriété d’un élément est réaffectée

/items/reassign

Tous les événements déclencheurs pour un élément en particulier

/items/<itemID>

Un élément en particulier est supprimé

/items/<itemID>/delete

Les propriétés d’un élément en particulier sont mises à jour

/items/<itemID>/update

La propriété d’un élément en particulier est modifié ou l’élément est déplacé

/items/<itemID>/move

Un élément en particulier est publié

/items/<itemID>/publish

Un élément en particulier est partagé

/items/<itemID>/share

Le partage d’un élément en particulier est annulé

/items/<itemID>/unshare

La propriété d’un élément en particulier est réaffectée

/items/<itemID>/reassign

Groupes

Toute modification générale apportée aux paramètres de groupe constitue une mise à jour. Par exemple, le changement d’accès d’un groupe déclenche un événement de mise à jour.

La table suivante répertorie les événements déclencheurs avec des groupes :

Événement déclencheurExemple d’URI

Tous les événements déclencheurs pour tous les groupes

/groups

Un groupe est ajouté

/groups/add

N’importe quel groupe est mis à jour

/groups/update

N’importe quel groupe est supprimé

/groups/delete

Le paramètre Delete Protection (Protection contre la suppression) est activé pour un groupe

/groups/protect

Le paramètre Delete Protection (Protection contre la suppression) est désactivé pour un groupe

/groups/unprotect

Un utilisateur est invité dans un groupe

/groups/invite

Un utilisateur est ajouté à un groupe

/groups/addUsers

Un utilisateur est supprimé d’un groupe

/groups/removeUsers

Le rôle d’un utilisateur est mis à jour dans un groupe

/groups/updateUsers

La propriété d’un groupe est réaffectée

/groups/reassign

Tous les événements déclencheurs pour un groupe en particulier

/groups/<groupID>

Un groupe en particulier est mis à jour

/groups/<groupID>/update

Un groupe en particulier est supprimé

/groups/<groupID>/delete

Le paramètre Delete Protection (Protection contre la suppression) est activé pour un groupe en particulier

/groups/<groupID>/protect

Le paramètre Delete Protection (Protection contre la suppression) est désactivé pour un groupe en particulier

/groups/<groupID>/unprotect

Un utilisateur est invité dans un groupe en particulier

/groups/<groupID>/invite

Un utilisateur est ajouté à un groupe en particulier

/groups/<groupID>/addUsers

Un utilisateur est supprimé d’un groupe en particulier

/groups/<groupID>/removeUsers

Le rôle d’un utilisateur est mis à jour dans un groupe en particulier

/groups/<groupID>/updateUsers

La propriété d’un groupe en particulier est réaffectée

/groups/<groupID>/reassign

Utilisateurs

Un événement de mise à jour est déclenché dès qu’une modification est apportée au profil de l’utilisateur. Toutefois, les modifications apportées au rôle d’un utilisateur, à un type d’utilisateur ou à une licence ne sont pas considérées comme une mise à jour du profil de l’utilisateur.

La table suivante répertorie les événements déclencheurs avec des utilisateurs :

Événement déclencheurExemple d’URI

Tous les événements déclencheurs pour tous les utilisateurs du portail

/users

Un utilisateur est ajouté à l’organisation

/users/add

N’importe quel utilisateur s’est connecté au portail

/users/signin

N’importe quel utilisateur s’est déconnecté du portail

/users/signout

N’importe quel utilisateur est supprimé

/users/delete

Le profil de n’importe quel utilisateur est mis à jour

/users/update

Le compte de n’importe quel utilisateur est désactivé

/users/disable

Le compte de n’importe quel utilisateur est activé

/users/enable

Un nouveau rôle a été affecté à n’importe quel utilisateur

/users/updateUserRole

Un type d’utilisateur a été affecté à n’importe quel utilisateur

/users/updateUserLicenseType

Tous les événements déclencheurs associés à un utilisateur en particulier

/users/<username>

Un utilisateur donné s’est connecté au portail

/users/<username>/signIn

Un utilisateur donné s’est déconnecté du portail

/users/<username>/signOut

Un utilisateur en particulier est supprimé

/users/<username>/delete

Le profil d’un utilisateur en particulier est mis à jour

/users/<username>/update

Le compte d’un utilisateur en particulier est désactivé

/users/<username>/disable

Le compte d’un utilisateur en particulier est activé

/users/<username>/enable

Un nouveau rôle a été affecté à un utilisateur en particulier

/users/<username>/updateUserRole

Un type d’utilisateur a été affecté à un utilisateur en particulier

/users/<username>/updateUserLicenseType

Rôles

Un événement de mise à jour est déclenché dès qu’une modification est apportée aux rôles de votre organisation.

La table suivante répertorie les événements déclencheurs avec des rôles d’utilisateur :

Événement déclencheurExemple d’URI

Tous les événements déclencheurs pour tous rôles du portail

/roles

Un nouveau rôle est créé

/roles/add

Un rôle existant est mis à jour

/roles/updated

Un rôle existant est supprimé

/roles/delete

Payloads

Une fois qu’un webhook est déclenché, une payload est livrée à la payload URL spécifique au format JSON. Chaque événement suit une structure JSON similaire avec des informations associées à l’événement.

CléTypeDescription
webhookName

chaîne

Nom du webhook qui a livré la payload.

webhookId

chaîne

ID du webhook qui a livré la payload.

portalURL

chaîne

URL du portail auprès duquel le webhook est inscrit.

when

timestamp

Heure de livraison de la payload.

username

chaîne

Utilisateur qui a déclenché l’événement.

userId

chaîne

ID de l’utilisateur qui a déclenché l’événement.

when

timestamp

Heure de l’événement.

operation

chaîne

Opération réalisée par l’utilisateur. Ce peut être, par exemple :

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

chaîne

Type d’élément sur lequel l’opération a été réalisée. Il peut s’agir de item, de group ou de user.

id

chaîne

ID de l’élément source sur lequel l’opération a été réalisée.

properties

objet

Propriétés supplémentaires associées à l’événement. Ce peut être, par exemple :

  • sharedToGroups : mode de partage d’un élément (ID de groupe, Organisation ou Tout le monde)
  • unsharedFromGroups : mode d’annulation du partage d’un élément (ID de groupe, Organisation ou Tout le monde)
  • removeUserNames : noms d’utilisateur correspondant aux utilisateurs supprimés d’un groupe
  • updateUserNames : noms d’utilisateur correspondant aux utilisateurs dont les rôles de groupe ont été mis à jour
  • invitedUserNames : noms d’utilisateur correspondant aux utilisateurs invités dans un groupe
  • addedUserNames : noms d’utilisateur correspondant aux utilisateurs qui ont été ajoutés dans un groupe
  • userRoleUpdatedTo : nouveau rôle attribué à l’utilisateur
  • reassignedTo : nouvel utilisateur auquel un élément ou un groupe a été réattribué
  • userLicenseTypeUpdatedTo : nouveau type d’utilisateur attribué à un utilisateur
  • name : nom du rôle qui a été créé, mis à jour ou supprimé

URL de charge utile

L’utilisateur doit fournir une payload URL lorsqu’il crée un webhook. Cela permet de définir le lieu de livraison de la payload. Comme la payload est livrée via une requête HTTPS POST, le récepteur du webhook doit être configuré de façon à communiquer via HTTPS et à être accessible par le portail. Vous pouvez utiliser plusieurs services Web, tels que Microsoft Power Automate, Zapier et IFFT, pour configurer des processus personnalisés avec votre payload. Vous pouvez par exemple créer un processus de sorte que lorsque Microsoft Power Automate reçoit une payload, il analyse et met en forme la payload et l’envoie à un alias de messagerie. Vous pouvez également créer et personnaliser votre service web de façon à recevoir des payloads. Pour les organisations qui limitent l’accès à Internet, la création d’un service web personnalisé pour recevoir les payloads est recommandée. Consultez nos exemples SDK d’entreprise pour un servlet Java prêt à l’emploi.

Payload d’exemple

Voici un exemple de payload illustrant la mise à jour d’un groupe spécifique :


{
   "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": {}
   }]
}

Créer un webhook

Les webhooks peuvent uniquement être administrés via le répertoire du portail ArcGIS (API de partage). Procédez comme suit pour créer un webhook :

  1. Accédez au répertoire Portal for ArcGIS.
    https://machine.domain.com/webadaptor/sharing/rest
  2. Connectez-vous en tant qu’administrateur.

    Les webhooks peuvent uniquement être créés et gérés par un administrateur.

    La page de l’administrateur apparaît.

  3. Cliquez sur l’hyperlien Org ID (ID d’org) ou émettez une requête au format ci-dessous, pour accéder à la page des ressources Portal Self.
    https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
  4. Faites défiler la page vers le bas, jusqu’à Webhooks, sous Child Resources (Ressources enfant).
    https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
  5. Sous Supported Operation (Opérations prises en charge), sélectionnez Create Webhook.
  6. Spécifiez les paramètres de votre webhook.

    Consultez la documentation REST API du webhook pour en savoir plus sur ces paramètres.

    Votre webhook est maintenant répertorié sous les webhooks : https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks

Gérer les webhooks

Vous pouvez gérer vos webhooks via le répertoire du portail ArcGIS en émettant une demande au format suivant :

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

Les opérations prises en charge pour gérer vos webhooks sont les suivantes :

  • Update Webhook : mettez à jour les paramètres de votre webhook. Vous pouvez modifier le nom, la payload URL, la configuration ou les événements déclencheurs pour le webhook spécifié.
  • Delete Webhook : supprimez le webhook de votre portail.
  • Deactivate Webhook et Activate Webhook : désactivez votre webhook, ce qui empêche les payloads d’être livrées lorsque le webhook est déclenché. Lorsque le webhook est désactivé, l’opération Activate Webhook (Activer le webhook) est disponible pour reprendre la livraison des payloads.

La page Notification Status affiche des informations sur les événements déclencheurs associés au webhook donné. Vous pouvez utiliser cette table pour surveiller votre webhook ainsi que les détails des payloads livrées, tels que l’heure à laquelle le webhook a été déclenché et les réponses reçues de la payload URL et de la payload livrée. Les enregistrements indiquant le succès de la livraison d’une payload sont supprimés au bout d’une journée. Les enregistrements indiquant l’échec d’une tentative de livraison sont stockés pendant sept jours.

Consultez Webhooks API pour des exemples sur ces opérations.

Configurer les paramètres avancés

Plusieurs paramètres avancés permettent de personnaliser davantage vos webhooks. Ils sont appliqués à tous les webhooks configurés dans votre portail et sont accessible depuis https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.

L’opération Update vous permet de mettre à jour les paramètres suivants :

  • Nombre de tentatives de livraison : indiquez le nombre de tentatives qui seront effectuées pour livrer une payload. Le nombre par défaut est de trois tentatives, mais vous pouvez l’augmenter à cinq au maximum.
  • Délai d’expiration de la notification : indiquez combien de temps une connexion va attendre la réception d’une réponse. Si aucune réponse n’est reçue pendant cet intervalle, la connexion expire et la tentative de notification est considérée comme ayant échoué.
  • Temps écoulé entre les tentatives de livraison : indiquez le temps entre chaque tentative de livraison de la payload. La valeur par défaut est de 30 secondes, mais vous pouvez l’augmenter à 100 secondes au maximum ou la réduire à 1 seconde au minimum.

Consultez la documentation sur l’API des webhooks pour plus d’informations sur la configuration des paramètres avancés.

Forum aux questions sur les webhooks

Les questions suivantes sont fréquemment posées lors de l’utilisation de webhooks.

ArcGIS Enterprise est déployé dans un environnement déconnecté derrière le pare-feu de mon organisation. Puis-je tout de même configurer des webhooks ?

Oui. Pour configurer des webhooks, vous devez utiliser une payload URL que votre portail ArcGIS Enterprise peut atteindre. Pour ce faire, vous pouvez créer une application personnalisée et la déployer sur votre serveur interne.

En quoi consiste la mise à jour d’un élément, d’un utilisateur ou d’un groupe ?

Si vous vous êtes abonné aux mises à jour pour les éléments, utilisateurs et groupes de votre portail, votre webhook se déclenche dès que leurs propriétés sont mises à jour. Par exemple, si vous vous êtes abonné aux mises à jour d’un élément spécifique sur votre portail, votre webhook se déclenche si une mise à jour est apportée au titre, aux étiquettes ou à la miniature de cet élément. Pour déterminer facilement si une action constitue une mise à jour de votre portail, examinez le trafic réseau. Chaque fois qu’une action engendre l’appel de l’opération Update (Mise à jour), cette même action peut également déclencher un webhook qui écoutera les mises à jour.

J’utilise l’authentification Windows intégrée sur mon portail ArcGIS Enterprise. Puis-je tout de même m’abonner à la connexion au portail des utilisateurs et à leur déconnexion (user/<username>/signIn) ?

À partir de la version 10.9, vous pouvez utiliser l’événement déclencheur /signin afin de capturer les événements de connexion pour l’authentification au niveau du portail ou au niveau du Web et les identifiants de connexion d’entreprise.

Que se passe-t-il si ma payload URL est indisponible ou ne fonctionne plus ? Existe-t-il un moyen de récupérer une payload qui n’a pas été livrée ?

Si le portail tente de livrer une payload à une payload URL ou à un récepteur de webhook qu’il ne parvient pas à atteindre ou qui ne répond pas, les paramètres avancés que vous avez définis déterminent comment et quand le portail tentera une nouvelle livraison. Si ces nouvelles tentatives ne permettent pas non plus de livrer la payload, cela compte comme un seul échec relatif au paramètre deactivationPolicy que vous avez configuré lors de la création du webhook. Le webhook se désactive une fois cette stratégie respectée.

Pour voir toutes les tentatives de livraison de la payload et déterminer si elles ont réussi ou non, vous pouvez consulter l’état de notification du webhook.