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.
Key terms
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 Power Automate, 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.
Items
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 | /items |
An item is added to the portal | /items/add |
Any item is deleted | /items/delete |
Any item is updated | /items/update |
Any item is moved or its ownership is changed | /items/move |
Any item is published | /items/publish |
Any item is shared | /items/share |
Any item is unshared | /items/unshare |
The ownership of any item has been reassigned | /items/reassign |
All trigger events for a specific item | /items/<itemID> |
A specific item is deleted | /items/<itemID>/delete |
A specific item's properties are updated | /items/<itemID>/update |
A specific item's ownership is changed or the item is moved | /items/<itemID>/move |
A specific item is published | /items/<itemID>/publish |
A specific item is shared | /items/<itemID>/share |
A specific item is unshared | /items/<itemID>/unshare |
The ownership of a specific item has been reassigned | /items/<itemID>/reassign |
Groups
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 | /groups |
A group is added | /groups/add |
Any group is updated | /groups/update |
Any group is deleted | /groups/delete |
Delete Protection is enabled for any group | /groups/protect |
Delete Protection is disabled for any group | /groups/unprotect |
A user is invited to any group | /groups/invite |
A user is added to any group | /groups/addUsers |
A user is removed from any group | /groups/removeUsers |
A user's role is updated in any group | /groups/updateUsers |
The ownership for any group has been reassigned | /groups/reassign |
All trigger events for a specific group | /groups/<groupID> |
A specific group is updated | /groups/<groupID>/update |
A specific group is deleted | /groups/<groupID>/delete |
Delete Protection is enabled for a specific group | /groups/<groupID>/protect |
Delete Protection is disabled for a specific group | /groups/<groupID>/unprotect |
A user is invited to a specific group | /groups/<groupID>/invite |
A user is added to a specific group | /groups/<groupID>/addUsers |
A user is removed from a specific group | /groups/<groupID>/removeUsers |
A user's role is updated in a specific group | /groups/<groupID>/updateUsers |
The ownership for a specific group has been reassigned | /groups/<groupID>/reassign |
Users
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 | /users |
A user is added to the organization | /users/add |
Any user has signed in to the portal | /users/signin |
Any user has signed out of the portal | /users/signout |
Any user is deleted | /users/delete |
Any user's profile is updated | /users/update |
Any user's account is disabled | /users/disable |
Any user's account is enabled | /users/enable |
Any user has been assigned a new role | /users/updateUserRole |
Any user has been assigned a new user type | /users/updateUserLicenseType |
All trigger events associated with a specific user | /users/<username> |
A specified user has signed in to the portal | /users/<username>/signIn |
A specified user has signed out of the portal | /users/<username>/signOut |
A specific user is deleted | /users/<username>/delete |
A specific user's profile is updated | /users/<username>/update |
A specific user's account is disabled | /users/<username>/disable |
A specific user's account is enabled | /users/<username>/enable |
A specific user has been assigned a new role | /users/<username>/updateUserRole |
A specific user has been assigned a new user type | /users/<username>/updateUserLicenseType |
Roles
An update event is trigged any time a change is made to your organization's roles.
The following table lists the trigger events associated with user roles:
| Trigger event | URI example |
|---|---|
All trigger events for all roles in the portal | /roles |
A new role is created | /roles/add |
An existing role is updated | /roles/updated |
An existing role is deleted | /roles/delete |
Payloads
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.
| Key | Type | Description |
|---|---|---|
| webhookName | string | The name of the webhook that delivered the payload. |
| webhookId | string | The ID of the webhook that delivered the payload. |
| portalURL | string | The URL of the portal that to which the webhook is registered. |
| when | timestamp | The time that the payload was delivered. |
| username | string | The user that triggered the event. |
| userId | string | The ID of the user that triggered the event. |
| when | timestamp | The time the event occurred. |
| operation | string | The operation performed by the user. This can be the following:
|
| source | string | The item type on which the operation was performed. This can be item, group, or user. |
| id | string | The ID of the source item on which the operation was performed. |
| properties | object | Additional properties associated with the event. This can be the following:
|
Payload URL
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 Power Automate, Zapier, and IFFT, to configure custom workflows with your payload. For example, you can create a workflow so that when Microsoft Power Automate 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.
Payload example
The following is a sample payload illustrating that a specific group has been updated:
{
"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": {}
}]
}
Create a webhook
Webhooks can only be administered through the ArcGIS Portal Directory (Sharing API). Use the following steps to create a webhook:
- Browse to the ArcGIS Portal Directory.https://machine.domain.com/webadaptor/sharing/rest
- Sign in as an administrator.
Webhooks can only be created and managed by an administrator.
The administrator 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://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
- Scroll to the bottom of the page to Webhooks, under Child Resources.https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/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://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks
Manage webhooks
You can manage your webhooks through the ArcGIS Portal Directory by making a request of the following form:
https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.
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://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/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
The following are common questions encountered when using webhooks.
ArcGIS Enterprise is deployed in a disconnected environment behind my organization's firewall. Can I still configure webhooks?
Yes. To configure webhooks, you must 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 triggers whenever their properties have been updated. For example, if you have subscribed to updates for a specific item in your portal, your webhook triggers if an update was made to the item's title, tags, or thumbnail. A way to determine whether an action constitutes an update in your portal is to examine the network traffic. Any time an action results in the Update operation being called, that same action can also 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)?
Starting at 10.9, you can use the /signin trigger event to capture sign in events for portal authentication, web-tier authentication, and enterprise logins.
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 counts as one failure toward the deactivationPolicy you set when creating the webhook. The webhook deactivates 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.