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 |
Ajouter un élément au portail | /items/add |
Tous les événements déclencheurs pour un élément en particulier | /items/<itemID> |
Supprimer un élément en particulier | /items/<itemID>/delete |
Mettre à jour les propriétés d’un élément en particulier | /items/<itemID>/update |
Déplacer un élément ou changer la propriété de l’élément | /items/<itemID>/move |
Publier un élément en particulier | /items/<itemID>/publish |
Partager un élément en particulier | /items/<itemID>/share |
Annuler le partage d’un élément en particulier | /items/<itemID>/unshare |
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 |
Ajouter un groupe | /groups/add |
Tous les événements déclencheurs pour un groupe en particulier | /groups/<groupID> |
Mettre à jour un groupe en particulier | /groups/<groupID>/update |
Supprimer un groupe en particulier | /groups/<groupID>/delete |
Activer l’option Delete Protection (Protection contre la suppression) pour un groupe en particulier | /groups/<groupID>/protect |
Désactiver l’option Delete Protection (Protection contre la suppression) pour un groupe en particulier | /groups/<groupID>/unprotect |
Inviter un utilisateur dans un groupe en particulier | /groups/<groupID>/invite |
Ajouter un utilisateur dans un groupe en particulier | /groups/<groupID>/addUsers |
Supprimer un utilisateur d’un groupe en particulier | /groups/<groupID>/removeUsers |
Mettre à jour le rôle d’un utilisateur dans un groupe en particulier | /groups/<groupID>/updateUsers |
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 |
Ajouter un utilisateur à l’organisation | /users/add |
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 |
Supprimer un utilisateur en particulier | /users/<username>/delete |
Mettre à jour le profil d’un utilisateur en particulier | /users/<username>/update |
Désactiver le compte d’un utilisateur en particulier | /users/<username>/disable |
Activer le compte d’un utilisateur en particulier | /users/<username>/enable |
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. Il peut s’agir de :
|
| 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. Il peut s’agir de :
|
Payload URL
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://machineURL/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 Portal for ArcGIS. Procédez comme suit pour créer un webhook :
- Accédez au répertoire Portal for ArcGIS.https://webadaptorhost.domain.com/webadaptorname/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Accédez au bas de la page, jusqu'à Webhooks sous Child Resources (Ressources enfant).https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
Gérer les webhooks
Vous pouvez gérer vos webhooks via le répertoire Portal for ArcGIS en émettant une requête au format suivant :
https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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 seront appliqués à tous les webhooks configurés dans votre portail et sont accessible depuis https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/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
My 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, échantillonnez le trafic réseau. Chaque fois qu’une action engendre l’appel de l’opération Update (Mise à jour), cette même action pourra é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) ?
Ces événements sont uniquement déclenchés lorsqu’un utilisateur se connecte ou se déconnecte via OAuth. C’est pourquoi l’authentification Windows intégrée (IWA) et les connexions SAML ne sont pas prises en charge. Cependant, la sécurité intégrée au portail et l’infrastructure à clé publique (PKI) prennent en charge les événements de connexion et de déconnexion.
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 comptera 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 ?