Skip To Content

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 eventURI example

All trigger events for all items

/items

Add item to the portal

/items/add

All trigger events for a specific item

/items/<itemID>

Delete a specific item

/items/<itemID>/delete

Update a specific item's properties

/items/<itemID>/update

Move an item or changing ownership of the item

/items/<itemID>/move

Publish a specific item

/items/<itemID>/publish

Share a specific item

/items/<itemID>/share

Unshare a specific item

/items/<itemID>/unshare

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 eventURI example

All trigger events for all groups

/groups

Add group

/groups/add

All trigger events for a specific group

/groups/<groupID>

Update a specific group

/groups/<groupID>/update

Delete a specific group

/groups/<groupID>/delete

Enable Delete Protection for a specific group

/groups/<groupID>/protect

Disable Delete Protection for a specific group

/groups/<groupID>/unprotect

Invite a user to a specific group

/groups/<groupID>/invite

Add a user to a specific group

/groups/<groupID>/addUsers

Remove a user from a specific group

/groups/<groupID>/removeUsers

Update a user's role in a specific group

/groups/<groupID>/updateUsers

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 eventURI example

All trigger events for all users in the portal

/users

Add a user to the organization

/users/add

All trigger events associated with a specific user

/users/<username>

A specified user has signed in to the portal

/users/<username>/signIn

A specified use has signed out of the portal

/users/<username>/signOut

Delete a specific user

/users/<username>/delete

Update a specific user's profile

/users/<username>/update

Disable a specific user's account

/users/<username>/disable

Enable a specific user's account

/users/<username>/enable

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.

KeyTypeDescription
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:

  • 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:

  • sharedToGroups — How an item is shared (groupID, Organization, or Everyone)
  • unsharedFromGroups — How an item is unshared (groupID, Organization, or Everyone)
  • removeUserNames — The usernames of users removed from a group
  • updateUserNames — The usernames of users whose group roles have been updated.
  • invitedUserNames — The usernames of users invited to a group.
  • addedUserNames — The usernames of users who have been added to a group

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://machineURL/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. Use the following steps to create a webhook:

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

    Webhooks can only be created and managed by an administrator.

    The admin 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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
  4. Scroll to the bottom of the page, to Webhooks under Child Resources.
    https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks

Manage webhooks

You can manage your webhooks through the ArcGIS Portal Directory by making a request of the following form:

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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://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.