Create and manage webhooks

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	Properties
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	sharedToGroups—How an item is shared (groupID, Organization, or Everyone) Examples, formatted for readability //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
A specific item is unshared	/items/<itemID>/unshare	unsharedFromGroups—How an item is unshared (groupID, Organization, or Everyone) Examples, formatted for readability //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
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	Properties
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	invitedUserNames—The user names of users invited to a group. Example, formatted for readability "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
A user is added to a specific group	/groups/<groupID>/addUsers	addedUserNames—The user names of users who have been added to a group. Example, formatted for readability "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
A user is removed from a specific group	/groups/<groupID>/removeUsers	removeUserNames—The user names of users removed from a group. Example, formatted for readability "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
A user's role is updated in a specific group	/groups/<groupID>/updateUsers	updateUserNames—The user names of users whose group roles have been updated. Example, formatted for readability "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
The ownership for a specific group has been reassigned	/groups/<groupID>/reassign
An item is shared to a group	/groups/<groupID>/itemShare	sharedItems—The itemID and item type of the item shared to a group. Example, formatted for readability "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
An item is unshared from a specific group	/groups/<groupID>/itemUnshare	unsharedItems—The itemID and item type of the item unshared from a group. Example, formatted for readability "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

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	Properties
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	userRoleUpdatedTo—The new role the user has been assigned to. Example, formatted for readability "properties": { "userRoleUpdatedTo": ["New role"] }
A specific user has been assigned a new user type	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo—The new user type that a user has been assigned to. Example, formatted for readability "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

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	Properties
All trigger events for all roles in the portal	/roles
A new role is created	/roles/add	name—The name of the role that has been created, updated, or deleted. Example, formatted for readability "properties": { "name": ["New role"] }
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: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
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: sharedToGroups—How an item is shared (groupID, Organization, or Everyone) unsharedFromGroups—How an item is unshared (groupID, Organization, or Everyone) removeUserNames—The user names of users removed from a group updateUserNames—The user names of users whose group roles have been updated. invitedUserNames—The user names of users invited to a group. addedUserNames—The user names of users who have been added to a group userRoleUpdatedTo—The new role the user has been assigned to reassignedTo—The new user an item or group has been reassigned to userLicenseTypeUpdatedTo—The new user type that a user has been assigned to name—The name of the role that has been created, updated, or deleted

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:

1. Browse to the ArcGIS Portal Directory.
   https://machine.domain.com/webadaptor/sharing/rest
2. Sign in as an administrator.

   Webhooks can only be created and managed by an administrator.

   The administrator user page appears.

3. 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>
4. Scroll to the bottom of the page to Webhooks, under Child Resources.
   https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
5. Under Supported Operation, select Create Webhook.
6. 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.