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éclencheur | Exemple 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éclencheur | Exemple 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éclencheur | Exemple 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éclencheur | Exemple 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é | Type | Description |
|---|---|---|
| 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 :
|
| 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 :
|
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 :
- Accédez au répertoire Portal for ArcGIS.https://organization.domain.com/context/sharing/rest
- 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.
- 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://organization.domain.com/context/sharing/rest/portals/<orgID>
- Faites défiler la page vers le bas, jusqu’à Webhooks, sous Child Resources (Ressources enfant).https://organization.domain/com/context/sharing/rest/portals/<orgID>/webhooks
- Sous Supported Operation (Opérations prises en charge), sélectionnez Create Webhook.
- 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://organization.domain.com/context/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://organization.domain.com/context/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://organization.domain.com/context/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.
Vous avez un commentaire à formuler concernant cette rubrique ?