Notification webhook payloads

As an ArcGIS Monitor administrator, you can configure notifications to send a webhook when specific events occur. Once a webhook is triggered, a payload is delivered to the specified webhook URL. Each webhook payload follows a similar JSON schema, containing information that is relevant to the event that triggered the payload. The sections below define webhook security, the properties included in the payloads, and an example of a webhook payload.

Webhook security

Monitor webhooks use signature verification to ensure the integrity and security of webhook payloads sent from Monitor to a webhook receiver. The input for the Webhook secret parameter acts as a shared secret key between both Monitor and the webhook receiver, which is known and stored independently by both Monitor and the webhook receiver and used to determine if the payload is trusted. When a webhook event is triggered, the secret key and the payload are hashed using an HMAC-SHA256 algorithm, which creates the signature. The signature is then passed in the webhook request as the x-esri Hook-Signature header value. When the webhook payload is delivered to the receiver, the receiver uses the secret key and payload to create a signature of its own using the same HMAC-SHA256 algorithm that Monitor used. If the signature included in the request header matches the recalculated value created by the webhook receiver, the webhook payload can be trusted by the receiver. Otherwise, the receiver may reject the incoming webhook payload.

The following Python function demonstrates how to validate a webhook payload:

import hashlib
import hmac

def verify_webhook_secret_hash(webhook_payload, webhook_secret, header_value):
    hash_obj = hmac.new(webhook_secret.encode('utf-8'), msg=webhook_payload, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_obj.hexdigest()
    if not hmac.compare_digest(expected_signature, header_value):
        print("Request signature didn't match expected signature!")
    else:
        print("Request signature matched expected signature!")

Payload properties

The following table lists the properties included in webhook payloads for notifications:

Property	Description
id	The ID of the notification that delivered the webhook.
name	The name of the notification that delivered the webhook.
monitor_url	The URL of the ArcGIS Monitor deployment that delivered the webhook.
version	The version of the Monitor deployment that delivered the webhook.
sent_at	The time the webhook was delivered.
trace_id	The unique ID of the webhook.
operation	Specifies the type of operation that was performed. The following are valid operations: Add Update Delete
resource	The item type on which the operation was performed.
occurred_at	The time the operation was performed.
attributes	The attributes associated with the specific event triggers. The following is a list of the attributes and properties included in the payload: Alerts Collections Components Incidents Observers

Notification payload example

The following is an example of a notification webhook payload that triggers when an alert has been updated:

{
  "info": {
    "id": "11",
    "name": "Production system events",
    "monitor_url": "https://monitorserver.domain.com/arcgis/",
    "version": "2023.0.0",
    "sent_at": 1543192196521,
    "trace_id": "c18bc20f-1267-4cee-85dd-324755675457"
  },
  "events": [
    {
      "operation": "update",
      "resource": "alerts",      
      "occurred_at": 1543192196521,
      "attributes": {
        …
      }
    }
  ]
}