/createWebhook: Create Webhook

Example usage

The following is a sample ArcGIS Enterprise POST request for the createWebhook operation that subscribes to all trigger events (allChanges):

1
2
3
4
5
6
POST /webadaptor/sharing/rest/portals/0123456789ABCDEF/webhooks/createWebhook HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

name=Microsoft Flow&url=https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow&secret=&config={"deactivationPolicy":{"numberOfFailures":5,"daysInPast":5}}&changes=allChanges&f=pjson

Description

The createWebhook operation allows portal administrators to create a new organization webhook. Administrators will specify the trigger events for this webhook, and the URL to which payloads are delivered when the webhook is invoked. For additional security, the secret parameter can be used to send a specific string that can be verified by the application listening on the payload URL. During the operation, the payload URL will be queried to confirm a connection to the portal is successful.

Request parameters

1
name=Microsoft Flow

1
url=https://app.logic.azure.com:443/workflows/dffb2e0433d245a3997e9d65a12f6ad2/triggers/manual/paths/invoke

1
secret=123456789ABCDE

1
2
config={
"deactivationPolicy":{"numberOfFailures": 5,"daysInPast": 5}}

1
2
3
4
5
6
7
8
config={
"deactivationPolicy": {"numberOfFailures": 5,"daysInPast": 5},
"properties": {
  "federatedServer": {
      "itemId": "<Notebook item id to be executed>",
      "tokenTypeToSend": "owner",
      "tokenExpirationTimeMinutes": 10}}
}

1
events=/items,/users

Supported trigger events

The events parameter can be used to manually define the events that will trigger the webhook. Trigger events are divided into four broad categories:

• Items
• Groups
• Users
• Roles

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 event triggers for your organization's items, which include web maps, web apps, layers, packages, and PDFs:

Item event trigger properties

Some of the event triggers for organization items return additional properties in their payloads. The sections below outline the additional payload properties for these triggers.

A specific item is shared

Webhooks that subscribe to the /items/<itemID>/share event trigger have the sharedToGroups property included in their payload. The sharedToGroups property specifies how an item was shared. If the item was shared with a group, the properties JSON object includes the ID for each group the item was shared with. If the item was shared with the organization as a whole, the object includes Organization. If the item was shared publicly, the object includes Everyone. The example below demonstrates sharing an item to specific groups, as well as sharing an item both publicly and to specific groups.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//groupIDs
"properties": {
  "sharedToGroups": [
    "ecd6646698b24180904e4888d5eaede3",
    "2dff15c514ad4f04b291e304e24a524b"
  ]
}

//Everyone and groupIDs
"properties": {
  "sharedToGroups": [
    "Everyone",
    "4adc30bb03054812a846fa592de105de",
    "a4e6e37e2f7d4bb5b64d587c91d39a2c"
  ]
}

Ownership of any item is reassigned

Webhooks that subscribe to the /items/reassign event trigger have the reassignedTo property included in their payload. The reassignedTo property specifies the new user an item or group is reassigned to, returning the username of the new owner in the properties JSON object.

1
2
3
"properties": {
  "reassignedTo": ["newOwner"]
}

A specific item is unshared

Webhooks that subscribe to the /items/<itemID>/unshare event trigger have the unsharedFromGroups property included in their payload. The unsharedFromGroups property specifies how an item was unshared. If the item was unshared from a group, the properties JSON object will include the IDs for each group the item was unshared from. If the item was unshared from the organization as a whole, the object includes Organization. If the item was unshared from the public, the object includes Everyone. The example properties below demonstrate unsharing an item from the public, as well as unsharing an item from a specific group.

1
2
3
4
5
6
7
8
9
10
11
//Everyone
"properties": {
  "unsharedFromGroups": ["Everyone"]
}

//groupID
"properties": {
  "unsharedFromGroups": [
    "4adc30bb03054812a846fa592de105de"
  ]
}

Ownership of a specific item is reassigned

Webhooks that subscribe to the /items/<itemID>/reassign event trigger have the reassignedTo property included in their payload. The reassignedTo property specifies the new user an item or group is assigned to, returning the username of the new owner in the properties JSON object.

1
2
3
"properties": {
  "reassignedTo": ["newOwner"]
}

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:

Group event trigger properties

Some of the event triggers for organization groups return additional properties in the payload. The sections below outline the additional payload properties for these triggers.

A user is invited to a specific group

Webhooks that subscribe to the /groups/<groupID>/invite event trigger have the invitedUserNames property included in their payload. The invitedUserNames property specifies the usernames of users invited to a group, returning a list of usernames in the properties JSON object.

1
2
3
4
5
6
"properties": {
  "invitedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

A user is added to a specific group

Webhooks that subscribe to the /groups/<groupID>/addUsers event trigger have the addedUserNames property included in their payload. The addedUserNames property specifies the usernames of users who have been added to a group, returning a list of usernames in the properties JSON object.

1
2
3
4
5
6
"properties": {
  "addedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

A user is removed from a specific group

Webhooks that subscribe to the /groups/<groupID>/removeUsers have the removeUserNames property included in their payload. The removeUserNames property specifies the usernames of users removed from a group, returning a list of usernames in the properties JSON object.

1
2
3
4
5
6
"properties": {
  "removedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

A user's role is updated in a specific group

Webhooks that subscribe to the /groups/<groupID>/updateUsers have the updateUserNames property included in their payload. The updateUserNames property specifies the usernames of users whose group roles have been updated, returning a list of usernames in the properties JSON object.

1
2
3
4
5
6
"properties": {
  "updatedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

An item is shared to a group

Webhooks that subscribe to the /groups/<groupID>/itemShare have the sharedItems property included in their payload. The sharedItems property specifies the itemID and item type of the item shared to a group, returning this information in the properties JSON object.

1
2
3
4
5
6
7
8
"properties": {
  "sharedItems": [
    {
      "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1",
      "itemType": "Map Package"
    }
  ]
}

An item is unshared from a specific group

Webhooks that subscribe to the /groups/<groupID>/itemUnshare have the unsharedItems property included in their payload. The unsharedItems property specifies the itemID and item type of the item unshared from a group, returning this information in the properties JSON object.

1
2
3
4
5
6
7
8
"properties": {
  "unsharedItems": [
    {
      "itemId": "7dd95fadaec84859ab8ed1059e675e0c",
      "itemType": "Image"
    }
  ]
}

Users

An update event is triggered anytime 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:

User event trigger properties

Some of the event triggers for organization users return additional properties in the payload. The sections below outline the additional payload properties for these triggers.

A specific user is assigned a new role

Webhooks that subscribe to the /users/<username>/updateUserRole have the userRoleUpdatedTo property included in their payload. The userRoleUpdatedTo property specifies the new role the user is assigned, returning the new role in the properties JSON object.

1
2
3
"properties": {
  "userRoleUpdatedTo": ["New role"]
}

A specific user is assigned a new user type

Webhooks that subscribe to the /users/<username>/updateUserLicenseType have the userLicenseTypeUpdatedTo property included in their payload. The userLicenseTypeUpdatedTo property specifies the new user type that a user is assigned, returning the new user type in the properties JSON object.

1
2
3
"properties": {
  "userLicenseTypeUpdatedTo": ["Editor"]
}

Roles

An update event is trigged anytime a change is made to your organization's roles.

The following table lists the trigger events associated with user roles:

Role event trigger properties

Some of the event triggers for organization roles return additional properties in the payload. The section below outlines the additional payload properties for these triggers.

A new role is created

Webhooks that subscribe to the /roles/add event trigger have the name property included in their payload. The name property specifies the name of the role that was created, returning the role's name in the properties JSON object.

1
2
3
"properties": {
  "name": ["New role"]
}

Trigger events

When creating your webhook, you are subscribing to the trigger events you specified during creation. The sections below demonstrate available trigger events.

Subscribe to all events

You can subscribe to all trigger events in Portal by using the forward slash (/) or by selecting the Send me everything option in the HTML view of the API. The following is a sample JSON response value where all events have been subscribed to:

1
events="/"

Subscribe to all events for a specific item type

You can subscribe to specific events for a specific item type (items, users, or groups). Subscribing to events associated to a specific item type will trigger the webhook anytime one of these item types is added, modified, or deleted. The following is a sample JSON response value where events pertaining to all items have been subscribed to:

1
events=/items

Subscribe to all events pertaining to a specific user

You can subscribe to events associated with a specific user. The following is a sample JSON response value where only events associated to a specific user will trigger the webhook:

1
events=/users/<username>

Subscribe to all events pertaining to a specific group

You can subscribe to events associated with a specific group. The following is a sample JSON response value where only an update to a specific group will trigger the webhook:

1
events=/groups/<groupId>/update

Subscribe to more than one trigger event

You can subscribe to a combination of trigger events by separating the URIs with commas within the parameter. The following is a sample JSON response value where more than one trigger event has been subscribed to:

1
events=/items,/groups/<groupId1>,/groups/<groupId2>

JSON Response example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "success": true,
  "webhook": {
    "id": "35f930b31df64b62873127613d047a1b",
    "accountId": "0123456789ABCDEF",
    "payloadUrl": "https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow",
    "secret": "",
    "isActive": true,
    "name": "Microsoft Flow",
    "config": {
      "deactivationPolicy": {
        "numberOfFailures": 5,
        "daysInPast": 5
      }
    },
    "ownerId": "8126a5f5ac674fbf98e746673c708b23",
    "modifiedId": "8126a5f5ac674fbf98e746673c708b23", //Introduced at ArcGIS Enterprise 11.1
    "created": 1600379506707,
    "modified": 1600379506707,
    "events": [
      "/"
    ]
  }
}