Webhooks integration for feature services

What are webhooks?

A webhook is a method that allows an application to automatically send real-time (or near real-time) data to another service whenever a specific event happens. Instead of repeatedly checking for updates, the system instantly delivers a notification as soon as the registered event occurs. Webhooks help to chain multiple processes, especially where the output of one is the input for the next.

When you configure a webhook for a feature service, ArcGIS Online will send HTTP POST requests to your specified endpoint whenever certain events occur in your hosted feature layer. This enables you to build reactive applications that respond immediately to data changes.

You use webhooks for:

• Real-time data synchronization between systems.
• Triggering automated workflows when data changes.
• Building event-driven applications.
• Reducing polling overhead and improving performance.

Prerequisites

Before you can set up webhooks for a feature service, ensure that:

• You have the appropriate permissions to create webhooks.
  • Organization administrators can create webhooks for any feature service in the organization.
  • Feature service owners can create webhooks for their own feature services.
  • Non-admin users with update control can create webhooks if they have update permissions through a shared update group.
• The hosted feature layer has Keep track of changes to the data enabled.
• Your webhook receiver endpoint is accessible and can handle HTTP POST requests.

How to create webhooks

The general steps to create webhooks are:

1. Start by creating webhooks through the Item Details > Settings > Webhooks interface for the most context-specific experience.
2. Use the Test functionality to verify your webhook receiver is working correctly.
3. Monitor webhook health and delivery status through My Settings > Webhooks for ongoing management.

Webhook events

Webhook events are specific conditions in a feature service that trigger a webhook request to be sent to your predefined URL. The following events are supported:

Webhook receivers

A webhook receiver is the endpoint (usually a URL) or service that listens for and processes incoming webhook requests. There are several types of webhook receivers you can use:

Custom receivers

This is the most flexible option and allows you to build your own custom webhook receiver. It allows you to process the payload and trigger custom business logic, update databases, or send notifications. You can use any programming language and framework you want to build your own custom webhook receiver.

1
https://your-app.com/webhook

Third-party automation services

Popular automation platforms that can receive webhooks and trigger automation workflows. You can use these platforms to process the payload and trigger custom business logic, update databases, or send notifications. These services are best for simple, automated workflows between different systems.

Below are some examples of popular automation platforms that can receive webhooks and trigger automation workflows:

• Zapier
• Make (formerly Integromat)
• Microsoft Power Automate
• Webhook.site

Cloud functions

Cloud functions are serverless functions that run when webhooks arrive. They are a popular choice for receiving webhooks and triggering automation workflows. You can use these platforms to process the payload and trigger custom business logic, update databases, or send notifications. These functions are best for complex, automated workflows that require more control over the processing, data handling, and integration with other systems.

Below are some examples of popular cloud functions:

• AWS Lambda
• Google Cloud Functions
• Azure Functions

Webhook payload

A webhook payload is the data that ArcGIS Online sends to your receiver when a webhook event is triggered. The payload is sent as JSON and contains details about the event and the changes that occurred.

Sample payload

1
2
3
4
5
6
7
8
9
{
  "name": "webhookBola11",
  "layerId": 0,
  "orgId": "CIPK1AQitSDS0McP",
  "serviceName": "webhookBola",
  "lastUpdatedTime": 1755719255181,
  "changesUrl": "https%3a%2f%2fservices2.arcgis.com%2fCIPK1AQitSDS0McP%2fArcGIS%2frest%2fservices%2fwebhookBola%2fFeatureServer%2fextractChanges%3fserverGens%3d%5b762039%2c762044%5d%26async%3dtrue%26returnAttachments%3dfalse",
  "events": ["FeaturesCreated", "FeaturesUpdated", "FeaturesDeleted"]
}

Accessing change data

The changesUrl in the payload is URL-encoded and contains a link to retrieve the actual change data. To access the changes:

1. Decode the URL using a URL decoder like meyerweb.com/eric/tools/dencoder/
2. Add your access token to the decoded URL
3. Make a request to the URL to retrieve the change data

Example decoded URL:

1
https://services2.arcgis.com/CIPK1AQitSDS0McP/ArcGIS/rest/services/webhookBola/FeatureServer/extractChanges?serverGens=[762039,762044]&async=true&returnAttachments=false&token=YOUR_ACCESS_TOKEN

Managing webhooks

Webhooks can be managed from three different locations in the ArcGIS Online interface, each designed for different use cases and user roles. The location you choose depends on your role and what you want to accomplish.

1. Organization Settings > Webhooks

Use this interface to configure organization-wide webhook policies, manage webhooks across multiple feature services, or enable/disable webhook functionality globally. Organization administrators can view, edit, delete, and activate/deactivate any webhook in the organization using the Turn On/Off toggle.

The typical workflow to access this location is:

1. Sign in to ArcGIS Online
2. Click your profile picture
3. Click Organization > Settings > Webhooks

2. My Settings > Webhooks

When you want to see all webhooks you have access to in one place, create new webhooks for feature services you own, or want a personalized view of your webhook activity.

The typical workflow to access this location is:

1. Sign in to ArcGIS Online
2. Click your profile picture
3. Click My Settings > Webhooks

3. Item Details > Settings > Webhooks

When you want to manage webhooks for a specific feature service, see which webhooks are configured for a particular layer, or create webhooks directly from the feature service context.

The typical workflow to access this location is:

1. Open a feature service item.
2. Click Item Details > Settings > Webhooks

Code examples

Below are practical examples showing how to create and handle webhooks for feature services:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
const webhookConfig = {
  name: "MyFeatureWebhook",
  changeTypes: "FeaturesCreated,FeaturesUpdated,FeaturesDeleted",
  hookUrl: "https://your-app.com/webhook-receiver",
  signatureKey: "your-secret-key",
  active: true,
  scheduleInfo: {
    name: "FeaturesWebhookSchedule",
    startAt: Date.now(),
    recurrenceInfo: {
      frequency: "second",
      interval: 20
    }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
// Webhook endpoint
app.post('/webhook-receiver', async (req, res) => {
  try {
    const payload = req.body;

    // Validate webhook signature (if configured)
    const signatureKey = "your-secret-key";
    const signature = req.headers['x-esri-signature'];
    if (signature) {
      const expectedSignature = crypto
        .createHmac('sha256', signatureKey)
        .update(JSON.stringify(payload))
        .digest('hex');

      if (signature !== expectedSignature) {
        return res.status(401).send('Invalid signature');
      }
    }

    console.log('Webhook received:', payload);
    console.log('Service:', payload.serviceName);
    console.log('Layer ID:', payload.layerId);
    console.log('Events:', payload.events);

    // Decode and process changesUrl
    const changesUrl = decodeURIComponent(payload.changesUrl);
    const changesUrlWithToken = `${changesUrl}&token=YOUR_ACCESS_TOKEN`;

    // Fetch the actual changes
    const changesResponse = await fetch(changesUrlWithToken);
    const changesData = await changesResponse.json();

    if (changesData.statusUrl) {
      // Poll for async job completion
      await pollJobStatus(changesData.statusUrl);
    }

    // Process the changes (add your business logic here)
    console.log('Changes retrieved successfully');

    // Acknowledge receipt
    res.status(200).send('Webhook received');

  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).send('Error processing webhook');
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
        # Process the changes
        if 'edits' in changes:
            for edit in changes['edits']:
                layer_id = edit.get('id')

                # Process inserts
                if 'adds' in edit and edit['adds']['features']:
                    print(f"Layer {layer_id}: {len(edit['adds']['features'])} features created")
                    for feature in edit['adds']['features']:
                        process_new_feature(feature)

                # Process updates
                if 'updates' in edit and edit['updates']['features']:
                    print(f"Layer {layer_id}: {len(edit['updates']['features'])} features updated")
                    for feature in edit['updates']['features']:
                        process_updated_feature(feature)

                # Process deletes
                if 'deletes' in edit and edit['deletes']:
                    print(f"Layer {layer_id}: {len(edit['deletes'])} features deleted")
                    for object_id in edit['deletes']:
                        process_deleted_feature(object_id)

        return changes

Best practices

When implementing webhooks for feature services:

• Verify signatures - Use the signature key to authenticate incoming webhook requests and prevent unauthorized access.
• Implement idempotency - Design your receiver to handle duplicate webhook deliveries gracefully using unique identifiers.
• Acknowledge fast, process asynchronously - Return a 200 status code immediately and process the webhook payload in a background queue.
• Handle async operations - Implement proper polling for the extractChanges async job to retrieve actual feature changes.

Additional resources

Esri maintains a comprehensive webhooks samples repository on GitHub with ready-to-use examples and integration patterns:

The samples include:

• Custom webhook receivers in multiple languages (Node.js, Python, Java)
• Third-party service integrations (Make, Microsoft Power Automate, Zapier, Tray.io, IFTTT )
• End-to-end workflow examples

These samples provide production-ready code you can adapt for your specific use cases and help you quickly implement webhook integrations with ArcGIS feature services.

Limitations

Be aware of the following limitations when using webhooks:

• Maximum 10 webhooks per feature layer - Each feature layer can have up to 10 webhooks configured.
• Change tracking required - The feature service must have change tracking enabled.
• Asynchronous processing - Change data retrieval is asynchronous and requires polling for completion.
• URL encoding - The changesUrl in payloads is URL-encoded and must be decoded before use.

Services

Tools