A webhook is a mechanism that allows an application to provide other applications with event-driven information. As an ArcGIS Enterprise portal administrator, you can create, manage, and configure webhooks. You can configure your webhooks to automatically notify you when events associated with your portal items, groups, and users occur. Once a webhook is triggered, an HTTP request is made to a unique, user-defined payload URL to provide information regarding the event.
The following are webhook key terms:
- Trigger Event —The operation you set to trigger your webhook. For example, you can configure your webhook to be triggered when a specific group is updated in your organization or when an item is shared. A webhook can have more than one trigger event.
- Payload—The trigger event data delivered by your webhook after the specified event has occurred. This information is formatted in JSON. See the Payloads section below for more information.
- Payload URL—The location where the payload will be sent. The payload URL can be created using a service such as Microsoft Flow, Zapier, or IFTTT. You can also create your own custom web service endpoint using a platform of your choice.
Example use case
Webhooks allow integration of workflows across systems, and there are many ways to take advantage of webhooks in your organization.
Monitor activity in ArcGIS Enterprise
A webhook can be used to monitor activity in ArcGIS Enterprise. For instance, you can subscribe to all events associated with a specific item. The webhook is triggered when the item's properties are updated, and an HTTPS request delivers a payload that contains data describing the event. You decide where this payload is delivered and can act accordingly upon receipt of the information.
Supported trigger events
When creating your webhook, you are subscribing to trigger events. As these events are portal operations, the URI to the operation must be provided in the webhook configuration. The subsections below describe the available trigger events and associated URI.
The item properties that can be updated vary between item types, and there are unique actions that trigger the /update operation. For example, if the item is a web map, updating the tag, configuring a pop-up, or changing the basemap are all update events that will trigger the webhook.
The following table lists the trigger events for supported portal items, which include web maps, web apps, layers, packages, PDF documents, and so on:
|Trigger event||URI example|
All trigger events for all items
Add item to the portal
All trigger events for a specific item
Delete a specific item
Update a specific item's properties
Move an item or changing ownership of the item
Publish a specific item
Share a specific item
Unshare a specific item
Any general changes made to the group settings constitute an update. For example, changing a group's access will trigger an update event.
The following table lists the trigger events associated with groups:
|Trigger event||URI example|
All trigger events for all groups
All trigger events for a specific group
Update a specific group
Delete a specific group
Enable Delete Protection for a specific group
Disable Delete Protection for a specific group
Invite a user to a specific group
Add a user to a specific group
Remove a user from a specific group
Update a user's role in a specific group
An update event is triggered any time a change is made to the user's profile. However, changes made to a user's role, user type, or license are not considered an update to the user's profile.
The following table lists the trigger events associated with users:
|Trigger event||URI example|
All trigger events for all users in the portal
Add a user to the organization
All trigger events associated with a specific user
A specified user has signed in to the portal
A specified use has signed out of the portal
Delete a specific user
Update a specific user's profile
Disable a specific user's account
Enable a specific user's account
Once a webhook is triggered, a payload is delivered to the specific payload URL in JSON format. Each event follows a similar JSON schema with information that is relevant to the event.
The name of the webhook that delivered the payload.
The ID of the webhook that delivered the payload.
The URL of the portal that to which the webhook is registered.
The time that the payload was delivered.
The user that triggered the event.
The ID of the user that triggered the event.
The time the event occurred.
The operation performed by the user. This can be:
The item type on which the operation was performed. This can be item, group, or user.
The ID of the source item on which the operation was performed.
Additional properties associated with the event. This can be:
A payload URL must be provided by the user when creating a webhook; this defines where the payload will be delivered. Since the payload is delivered through an HTTPS POST request, the webhook receiver should be configured to communicate over HTTPS and be reachable by the portal. You can use multiple web services, such as Microsoft Flow, Zapier, and IFFT, to configure custom workflows with your payload. For example, you can create a workflow so that when Microsoft Flow receives a payload, it parses and format the payload and sends it to an email alias. Alternatively, you can build and customize your web service to receive payloads. For organizations that restrict Internet access, building a custom web service to receive payloads is recommended. See our Enterprise SDK samples for a ready-to-use Java servlet.
The following is a sample payload illustrating that a specific group has been updated:
"webhookName": "Group monitoring",
Create a webhook
Webhooks can only be administered through the ArcGIS Portal Directory. Use the following steps to create a webhook:
- Browse to the ArcGIS Portal Directory.https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Sign in as an administrator.
Webhooks can only be created and managed by an administrator.
The admin user page appears.
- Click the Org ID hyperlink, or make a request of the form below, to go to the Portal Self resource page.https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Scroll to the bottom of the page, to Webhooks under Child Resources.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
- Under Supported Operation, select Create Webhook.
- Specify the parameters for your webhook.
See the webhook REST API documentation for details about these parameters.
Your webhook is now listed under webhooks. https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
You can manage your webhooks through the ArcGIS Portal Directory by making a request of the following form:
The supported operations for managing your webhooks are as follows:
- Update Webhook — Update your webhook's parameters. You can update the name, payload URL, configuration, or trigger events for the specified webhook.
- Delete Webhook — Remove the webhook from your portal.
- Deactivate Webhook and Activate Webhook — Deactivate your webhook, which stops payloads from being delivered when the webhook is triggered. When the webhook is deactivated, the Activate Webhook operation is available to resume delivery of payloads.
The Notification Status page displays information relating to trigger events associated with the specific webhook. You can use this table to monitor your webhook as well as details of delivered payloads, such as the time the webhook was triggered and the responses received from the payload URL and the delivered payload. Records indicating the successful delivery of a payload are removed after one day. Records indicating a failed delivery attempt are stored for seven days.
See the Webhooks API for examples of these operations.
Configure advanced parameters
There are several advanced parameters that can be used to further customize your webhooks. These parameters will be applied to all configured webhooks in your portal and can be accessed from https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/webhooks/settings.
The Update operation allows you to update the following parameters:
- Number of delivery attempts — Specify the number of attempts that will be made to deliver a payload. The default is three attempts, and it can be increased up to five attempts.
- Notification timeout — Specify the length of time a connection will wait to receive a response. If a response is not received within this interval, the connection will time out and is considered a failed notification attempt.
- Elapsed time between delivery attempts — Specify the time between each payload delivery attempt. The default is 30 seconds, and it can be increased to a maximum of 100 seconds or decreased to a minimum of 1 second.
See the webhooks API documentation for more information on how to configure advanced parameters.
Webhooks frequently asked questions
My ArcGIS Enterprise is deployed in a disconnected environment behind my organization's firewall. Can I still configure webhooks?
Yes. To configure webhooks, you will need to use a payload URL that is reachable by your ArcGIS Enterprise portal. To do so, you can build a custom application and deploy it on your internal server.
What constitutes an update for an item, user, or group?
If you subscribed to updates for your portal items, users, and groups, your webhook will trigger whenever their properties have been updated. For example, if you have subscribed to updates for a specific item in your portal, your webhook would trigger if an update was made to the item's title, tags, or thumbnail. An easy way to determine whether an action constitutes an update in your portal is to example your the network traffic. Any time an action results in the Update operation being called, that same action will also be able to trigger a webhook that is listening for updates.
I am using Integrated Windows Authentication in my ArcGIS Enterprise portal. Can I still subscribe to user's signing in and out of the portal (user/<username>/signIn)?
These events are only triggered when a user signs in or out via OAuth. Therefore, Integrated Windows Authentication (IWA) and SAML are not supported. However, portal's built-in security and PKI do support the sign in and sign out events.
What happens if my payload URL goes down, or becomes unavailable? Is there a way to recover a payload that was not delivered?
If portal attempts to deliver a payload to an unreachable or non-responsive payload URL or webhook receiver, the advanced parameters you have set will determine how and when portal attempts another delivery. If these additional attempts also fail to deliver the payload, this will count as one failure towards the deactivationPolicy you set when creating the webhook. The webhook will deactivate once this policy has been met.
You can go to the webhook's notification status to view all of the attempted payload deliveries, and determine whether they were delivered successfully or not.