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 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.
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 |
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 event | URI 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 event | URI example |
|---|---|
All trigger events for all users in the portal | /users |
All trigger events associated with a specific user | /users/<username> |
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.
| 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:
|
| 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:
|
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 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.
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:
- 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
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.