Automate notebook workflows with webhook events

A webhook is a mechanism that allows an application to provide other applications with event-driven information. Webhooks can be configured at the organization and service levels to automatically run a notebook when events associated with your organization or services occur.

Automate a notebook using organization webhooks

As an ArcGIS Enterprise administrator or a user with the Organization webhooks privilege, you can create, manage, and configure webhooks. You can configure webhooks to automatically run a notebook you own when events associated with your items, groups, or users occur. ArcGIS Notebook Server acts as the receiver of the webhook payload. Once a webhook is triggered, an HTTP request is made to ArcGIS Notebook Server to run a chosen notebook without any user interaction.

Note:

The number of concurrently running notebooks from webhooks is limited by the maxExecuteNotebookContainersPerNode system property in ArcGIS Notebook Server.

Create an organization webhook

Webhooks can be administered from your Organization settings page. Use the following steps to create a webhook:

1. Sign in as a default administrator or custom role with the Organization webhooks privilege.
2. Click Organization > Settings > Webhooks.
3. In the Organization webhooks section, click Create webhook.
4. Specify a webhook name.
5. Select the type of event that will trigger the webhook.

   By default, all event types (Items, Users, Groups, and Roles) are considered.

   See Supported trigger events for more information.

6. Select Notebook as the payload type.

   Note:

   If the Notebook option is not available, Notebook Server has not been configured with your portal. If the Notebook option is available but cannot be selected, you do not own any notebooks that are available for configuring webhooks. You must own the notebook item that will be used for the webhook.

7. Select the notebook that will run when the webhook is triggered.
8. Optionally, enter a Secret key that will be included in the webhook payload.

   You can also choose to use random, pregenerated values for the Secret key.

9. Click Create webhook to save the webhook settings and create a webhook.

Manage organization webhooks

Webhooks can be administered from your Organization settings page. Use the following steps to manage existing webhooks:

1. Sign in as a default administrator or as a custom role with the Organization webhooks privilege.
2. Click Organization > Settings > Webhooks to see a list of Organization webhooks created by you and other webhook administrators.

You can manage your existing webhooks with the following operations.

• Deactivate webhook—When a webhook is in an active state, click Active. Deactivating the webhook stops payloads from being delivered when the webhook is triggered.
• Activate webhook—When a webhook is in an inactive state, click Inactive. Once a webhook is activated, it will resume delivery of payloads.
• Edit webhook—Click the options button on the webhook and click Edit to update your webhook.
• Delete webhook—Click the options button on the webhook and click Delete. Click Confirm to delete the webhook.

Modify Advanced organization webhook settings

Use Advanced webhook settings to change properties such as the number of delivery attempts that can be made, notifications for elapsed time, and notification timeout properties for webhooks. These advanced settings will apply to all webhooks in your organization. To modify the Advanced webhook settings, complete the following steps:

1. Sign in as a default administrator or as a custom role with the Organization webhooks privilege.
2. Click Organization > Settings > Webhooks.
3. In the Organization webhooks section, click Advanced settings to modify the default values of the Advanced webhook properties.

Payload of organization webhooks

When a notebook is run from a webhook, the webhook's payload information is automatically injected into the notebook in an initial cell. Once injected, the information provided in the webhook payload can be used in the notebook for further automation workflows.

Webhook payload information included in a notebook:

webhookPayload = {
    "properties": {
        "itemId": "<notebook_item_id>"
    },
    "events": [
        {
            "source": "<items | user | group | role>",
            "id": "<source_id>",
            "userId": "<user_id_of_member_triggered_webhook>",
            "when": 1742596800000,
            "operation": "<operation_triggered_webhook>",
            "properties": {"<operation_details>"},
            "username": "<username_of_member_triggered_webhook>"
        }
    ],
    "info": {
        "webhookId": "<webhook_id>",
        "portalURL": "<portal_url>",
        "webhookName": "<webhook_name>",
        "when": 1742596805000
    }
}

Automate a notebook using service webhooks

Webhooks—including those for asynchronous geoprocessing services, feature services, and other generic webhooks—can trigger a notebook run in response to specific events. Administrators can register a webhook receiver URL as the hook or payload URL for these webhooks. When a specific event associated with a webhook is triggered, it will automatically call the Notebook Webhook Receiver URL, initiating the run of the corresponding notebook.

The following sections describe how to configure a notebook webhook receiver in ArcGIS Notebook Server.

Create and copy an API key

An API key is a long-lived token that authorizes a service webhook to run an associated notebook item and securely access the ArcGIS Enterprise capabilities and functionality required for the notebook to run.

API keys are generated using API key credentials, a type of item hosted in your organization. API key credentials contain settings that allow you to generate API keys and manage properties such as their privileges and expiration date. The process of creating API key credentials and using API keys in your application is known as API key authentication.

To create and copy an API key, complete the following steps:

1. Sign in to your portal as an administrative user.
2. Click the Item Details page of the API key item.
3. Follow the steps in the Create an API key tutorial for steps on how to create and copy an API key. Grant the Create and edit Notebooks, Create, Update, and Delete item privileges, and, optionally, grant the Advanced notebook privilege for ArcPy.

   Additional privileges may be required depending on the workflows performed in the notebook.

Register a notebook webhook receiver

To register a notebook webhook receiver, complete the following steps:

1. Sign in to your portal as an administrator.
2. Click Organization > Settings > webhooks > Create webhook receiver.
3. Type a name for your webhook receiver.
4. Select the notebook that the webhook receiver will run.
5. Enter a 32-character secret key that will be used to ensure the origin of the webhook.
6. Enter a comma-separated list of signature headers that will be checked for an encrypted payload.
7. Enter the API token with privileges to access the notebook item, Create Notebook/Create Advanced Notebook privileges, and any other GIS capabilities in the notebook.
8. Optionally, enter parameters in the JSON format.
9. Click Create receiver.

Create an asynchronous geoprocessing service or feature service webhook

To create an asynchronous geoprocessing service or feature service webhook, complete the following steps:

1. Use the webhook receiver URL, secret headers, and signature headers to create a service webhook.
2. Validate that the notebook associated with the notebook webhook receiver runs each time a specific service webhook event is triggered.

Payload of service webhooks

When a notebook is run from a webhook, the webhook's payload information is automatically injected into the notebook in an initial cell. Once injected, the information provided in the webhook payload can be used in the notebook for further automation workflows.

Feature service webhooks

The following code is an example of a payload for a feature service webhook.

webhookPayload = {
    "serviceType": "FeatureServer",
    "changesUrl": "<change_url>",
    "name": "<webhook_name>",
    "id": "<webhook_id>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "FeaturesCreated",
            "when": 1740436800000
        },
        {
            "eventType": "FeaturesDeleted",
            "when": 1740436810000
        },
        {
            "eventType": "FeaturesUpdated",
            "when": 1740436820000
        }
    ]
}

Geoprocessing service webhooks

The following code is an example of a payload for a geoprocessing service webhook.

webhookPayload = {
    "serviceType": "GPServer",
    "jobId": "<job_id>",
    "statusURL": "<status_url>",
    "name": "<webhook_name>",
    "taskName": "<task_name>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "esriJobSucceeded",
            "when": 1742337000000
        }
    ]
}