/createWebhook: Create Webhook

• URL:https://[root]/portals/[portalID]/webhooks/createWebhook(POST only)
  
• Version Introduced:10.7

Example usage

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

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

Parameter	Details
name (Required)	Specifies the webhook's name. Example name=Microsoft Flow
url (Required)	Identifies the payload URL. Note: The payload URL is not required when configuring a webhook for notebooks, as the system will automatically derive it. Example 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 (Optional)	A user-defined element that can be added to the payload to help authenticate the message on your receiver. When used, the secret will be added to the header of the webhook payload. The application receiver will use the secret value in the payload's header to help authenticate the message. Example secret=123456789ABCDE
config (Optional)	Sets the configuration properties for your webhook. Note: The payload URL is not required when configuring a webhook for notebooks, as the system will automatically derive it. Example without properties: config={ "deactivationPolicy":{"numberOfFailures": 5,"daysInPast": 5}} Notebook example with properties: config={ "deactivationPolicy": {"numberOfFailures": 5,"daysInPast": 5}, "properties": { "federatedServer": { "itemId": "<Notebook item id to be executed>", "tokenTypeToSend": "owner", "tokenExpirationTimeMinutes": 10}} }
changes (Required)	If manual is specified, the events parameter will need to be included in the request. Selecting allChanges will cause all possible events to trigger the webhook. The default value is manualChanges. Values: manualChanges | allChanges
events (Optional)	This parameter is required if changes is specified as manual. The URI representation of an event that will trigger the webhook. For more information, see the Supported trigger events section below. For additional examples of trigger events, see the Trigger events section below. Example events=/items,/users
f	The response format. The default format is html. Values: html | json | pjson

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 trigger events for supported portal items, which include web maps, web apps, layers, packages, and PDF documents:

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
An item is shared to any group	/groups/itemShare
An item is unshared from any group	/groups/itemUnshare
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 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:

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
A list of user accounts has been enabled	/users/bulkEnable
A list of user accounts has been disabled	/users/bulkDisable
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 anytime 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/update
An existing role is deleted	/roles/delete

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:

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:

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:

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:

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:

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

JSON Response example

{
  "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",
    
    "created": 1600379506707,
    "modified": 1600379506707,
    "events": [
      "/"
    ]
  }
}