Webhooks - Don't call us, we'll call you

At our annual Esri Developer Summit, one of the new exciting features showcased during the plenary was the ability to create webhooks in ArcGIS Enterprise 10.7. Users (you) were clearly excited by this, and throughout the week we met with many users who shared their amazing ideas about how they would start implementing webhooks in their organizations.  One user had a very intricate workflow that they were looking to optimize through webhooks, and their idea exemplified everything that webhooks were intended to be – a tool which allows you to build event-driven, automated workflows.

Whether or not you have heard of webhooks, by the end of this blog you will hopefully walk away with some inspiration to start implementing them yourself!

The task

This user worked for an organization that had a number of procedures that needed to be executed every time a new item was added to their organization’s portal.  These procedures included:

• Vetting each new item for metadata completeness,
• Applying organization standard thumbnails, tags, and descriptions
• And running a script to replicate their primary deployment to a standby deployment so that any new item added to the primary site, was also created in the standby.

Essentially this user needed an efficient way to determine when a new item was added in the ArcGIS Enterprise portal.  The randomness of this event was a challenge in itself, so they needed a solution which would allow them to identify that an item was added, and react to this event in a timely manner.  Let’s look at some of the ways this task can be approached:

Option A – Manually track and count the items

Depending on the number of users in your organization and the level of activity, maybe sorting the items by date or counting the items throughout the day is a feasible solution.  But of course this solution would quickly reach some limits as items are added more frequently. And we are sure you have more important things to do than count the items in your portal.

Option B – Poll the ArcGIS REST API

A more advanced administrator may write a script to call the ArcGIS REST API at a set interval to determine whether any new items have been added to the portal.

I know that this is very similar to what many of you are doing today.  Polling our APIs to detect changes in your organization and to your content.  Changes that your operational workflows are dependent on.  But this also has its restrictions.  It’s not the most efficient way to gather information, and because these events generally happen spontaneously it leaves opportunity for staleness in your processes.

Option C – Use Webhooks

The most advanced among us will want to hand this task off to the system, and ask to be notified any time a new item is added in portal – and you can now achieve this using webhooks in ArcGIS Enterprise 10.7.  Webhooks allow administrators to subscribe to events in their portals, and be notified any time that event occurs.  So how exactly does this work?  Let’s break it down.

We begin by creating a webhook in our organization.  Since we want to know when a new item is added in portal, we configure the webhook to “subscribe” to the Add Item event.  Now any time a new item is added to the portal, the webhook will be triggered.

When configuring the webhook, we will have to provide a URL to an application or service (also known as the payload URL) that is listening for HTTPS POST requests.  You have all the control over where your payload is delivered. You can utilize one of many available web services like Microsoft Flow, Zapier, Integromat etc.  These services allow you to create automated workflows and come built-in with many different applications like Outlook, Slack, Power BI, and much much more.  For instance, you can use Zapier to build a workflow that sends out an email or Slack message any time a new item is added in the organization.

The payload URL may also be an application that you have deployed on your local servers. This is a great option for organizations that operate in disconnected environments.
Check out some sample applications our development team has written to help get you started with building your own webhook receiver:

https://github.com/Esri/webhooks-samples/

Once the webhook is triggered, it will automatically send out a payload that will include high-level information about the event.

In this case the payload will include information such as: which user added the item, and the new item’s ID.  We can use this information to call back into the portal and run a targeted process on this item.

{
“info”: {
“webhookId”: “e893a2b8ff3a40f49a9537236c006dce”,
“webhookName”: “New items added”,
“portalURL”: “https://yourPortalURL.com/portal/”,
“when”: 1544481891249
},
“events”: [{
“userId”: “0a9c99cf4392495585a6f1d34971a2aa”,
“username”: “publisher”,
“when”: 1544481889202,
“operation”: “add”,
“source”: “item”,
“id”: “eea1bac77ce44514b85ec604b16ab7f0”,
“properties”: {}
}]
}

Now that we’ve handed this task off to the system, we can start building our external workflows to react to these events.  This is just one of many examples of how webhooks in ArcGIS Enterprise 10.7 can help you efficiently administrate your ArcGIS Enterprise portal.

To learn more about webhooks and creating them in ArcGIS Enterprise, please review the Portal documentation, and the ArcGIS REST API.

I can’t wait to see and hear about how you start increasing your organization’s efficiency through webhooks!