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.

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.

//groupIDs
"properties": {
  "sharedToGroups": [
    "ecd6646698b24180904e4888d5eaede3",
    "2dff15c514ad4f04b291e304e24a524b"
  ]
}

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

//Everyone
"properties": {
  "unsharedFromGroups": ["Everyone"]
}

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

"properties": {
  "invitedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "addedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "removedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "updatedUserNames": [
    "u1TestUser",
    "u2TestUser"
  ]
}

"properties": {
  "sharedItems": [
    {
      "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1",
      "itemType": "Map Package"
    }
  ]
}

"properties": {
  "unsharedItems": [
    {
      "itemId": "7dd95fadaec84859ab8ed1059e675e0c",
      "itemType": "Image"
    }
  ]
}

"properties": {
  "userRoleUpdatedTo": ["New role"]
}

"properties": {
  "userLicenseTypeUpdatedTo": ["Editor"]
}

"properties": {
  "name": ["New role"]
}

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.

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.

{
  "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

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.