Webhooks for the ArcGIS Administrator

For developers, the idea of a hook has been around for quite a while.  It’s a commonly used mechanism developers use for allowing one piece of code to interact or modify another piece of code. This concept has been extended in recent years and in 2007 Jeff Lindsay coined the term webhook.

A Webhook allows one application to provide another application with event-driven data.

Ok great!! So, what does that actually mean?

Let’s use a real-world example as an analogy – Let say you place an order with an online retailer for a new pair of kicks (aka shoes). You provide all your contact information, including email address and phone number when you submit your order online. How do you know that your order has been received or when it has been dispatched for delivery? Should you make regular calls to the retailer requesting an update on the shipping status or simply wait for the retailer to send you an automated email or text message as/when the status changes?

Let’s go with the latter.

Webhooks operate on this principal, when an event is triggered, (i.e. an update on a user/item/group), a payload will be sent to a recipient.

Let’s look at some key terms to help us understand the concept a little better:

A trigger event is an operation you set to trigger an event. In the analogy above, the trigger event would be when an update occurs to the shipping status.

The Payload – This is the trigger event data that is delivered by your webhook. Using the same analogy, the payload would contain the current status of your delivery (i.e. Parcel left warehouse, with courier, en-route etc)

Payload URL – This is the location where the payload will be sent. Sticking with the same analogy, the payload URL would be the customers phone number or email address. In a real world scenario, the payload URL would resolve to a services such as Integromat,  Microsoft Power Automate or Zapier as the recipient for the payload, where further intelligence or alerting can be applied. 
 

Well, as of ArcGIS Enterprise 10.7, Webhooks have been introduced as a configurable out-of-the-box admin tool which can be configured via the Portal Admin Rest API. As an ArcGIS Enterprise Portal administrator, you can now create, manage and configure webhooks to monitor activity on your Portal assets, such as users, groups and items. These webhooks can then be received by or integrated with other third-party services as mentioned above. 
 

So now we understand what a webhook is – how can we use them?

The following section explores a use case for creating a webhook in Portal for ArcGIS, integrating the webhook with Microsoft Power Automate which finally alerts into Microsoft Teams upon an event trigger.

The use case is described below –

An organisation is currently digitising planning applications within their local zone using a WebApp which is hosted on their on-premise ArcGIS Enterprise. The planning applications are shared within two specific groups. One of the groups is utilised as a Collaboration workspace with the purpose of collaborating the planning applications to ArcGIS Online for public consumption. If the Feature layer or group is deleted, we want an alert sent to the GIS Administrators Channel in Microsoft Teams. In addition – if the item is unshared or delete protection is disabled on the group, we also wish to notify our GIS Administrators on the Microsoft Teams channel, so that they may act. 
 

To create a webhook we will need to access the Portals Sharing API – See the URL below. Note you should modify this URL to reflect your own ArcGIS Enterprise.

https://<yourGISserver>/portal/sharing/rest/self

You should then navigate to the admin directory in the community/user tab and click on your organisation ID. Note Be sure to login to your Portal as a GIS Administrator. Use care as this interface is for advanced users.
 

From here, you will be able to create your first webbook – Click Webhooks on the bottom of the webpage and select create webhook. Enter an appropriate name for your webhook, next you need to identify the item ID’s of the groups and services you wish to monitor. To do this you should search Portal for ArcGIS for the appropriate items and obtain the ID for each item from the URL in the browser.
 

The payload URL can only be populated once you configure your listening service, which we will get to the in the next section (Create the payload receiver). For now you can specify the appropriate events you would like to trigger the webhook.
 

In this particular use case, we want our webhook to trigger when a specific feature layer is deleted or unshared. This is achieved by using /items/<itemid>/delete and /items/<itemid>/unshare in the “Update the events you would like to trigger this webhook” box.

We are also monitoring the group for the removal of delete protection and the unsharing of the group. 
 

Before you finalise the creation of the webhook, you need to specify the Payload URL  – leave the webhook page open and now let’s switch over to Microsoft Power Automate.

Top tip – In this use case, the webhook is being configured to trigger on specific items. You can configure a webhook to monitor more generic activity on your portal, the creation of any new group, item or user. For a full list of supported trigger events please see the following article on common administrative tasks.
 

Within Microsoft Power Automate, you will need to create a receiver that will listen for the Portal for ArcGIS Web trigger events and then pass them onto a Microsoft Teams channel. Within Microsoft Power Automate you should create a new automated flow using a blank template. You then need to use “When a HTTP request is received” as your flows action.  Copy the payload sample provided by the Esri online documentation and paste it into “Use sample payload to generate schema.”
 

Next -  you need to select what action should occur once the payload has been received – search for Microsoft Teams and select “Post a message as the flow bot to a channel.” Specify a team and a channel – and update the message as appropriate.

Top tip the team channel could be a dedicated channel for your GIS Administrators – to be notified of events occurring in your GIS Portal. 
 

Top tip

When configuring your action event (for example, a team’s notification event), ensure you utilise the dynamic events from the payload to obtain useful information on the trigger event. In the example above we are obtaining the webhook name, operation carried out on the item (unshared, delete, etc), username that initiated the trigger, the Portal for ArcGIS URL. This information is then passed into the team’s notification action event.
 

Once the flow has been saved – copy the payload receiver URL.
 

With the payload receiver created – you can then return to your ArcGIS Portal Webook page and paste the previously copied URL for the receiver into “Payload URL”. Click on create webhook.
 

Now that we have configured the webhook – let’s see it in action. For the purposes of this demo we will remove delete protection from a specific group, and unshare the feature layer. Although only one webhook is configured, you should expect to receive individual notifications for each trigger event configured in your webhook. 
 

So there we have it – it really is that simple! We are now getting real-time updates on our items in Portal without any sophisticated scripting to the REST API, or scheduled polling events. We are now proactively monitoring our Portal and can respond to events as they happen, as opposed to waiting for a ticket or call from members of the public. 
 

For me, the adoption of Webhooks into Portal for ArcGIS and more recently in ArcGIS Online is an exciting and powerful development within the platform.

The step-by-step approach I’ve taken in this article show how  events can be triggered on all your portal assets, users, groups and items in real-time. We can gain insight into the type of action that occurred, what item it occurred on and by whom. The best thing of all is, the webhook events are trigged in portal as they occur. This hands responsibility over to the GIS system, removing the dependencies on manual tracking or advanced scripting using the REST API.

The integration of webhooks with third party services opens new realms of possibilities, from alerting in popular messaging platforms, applying additional validation or intelligence with ArcPy scripting or monitoring change in your GIS through a combination of Webhooks, Integration and ArcGIS dashboards.

The only limit is your imagination – the next step is to start configuring some Webhooks of your own – here is a good start, or feel free to reach out to find out how we can help get you setup via mapsmakesense@esri-ireland.ie