Understanding how Change Notifications work

Change Notifications requires the implementation of a custom webhook handler (such as Microsoft Azure) to receive events and take additional actions as desired. Before you can begin using Change Notifications, you must have a webhook handler endpoint URL.

The verification of the Endpoint URL occurs when Verify and Save is clicked (Settings > Change Notifications). During verification, Azure sends an Endpoint Validation Event to the Endpoint URL entered.

Below is an example of the Endpoint Validation Event and potential Response Options. In order to complete validation, it is your application’s responsibility to properly respond to the event.

Endpoint Validation Event Example

The following is an example of the Endpoint Validation Event that occurs when iMIS is verifying the Endpoint URL:

[ 
  { 
    "id": "2a7c415f-a534-4269-8e35-62122a010503", 
    "topic": "/subscriptions/0ea11a68-4102-467a-9b0f-0637a0f176e0/resourceGroups/shared-region0-rg/providers/microsoft.eventgrid/domains/shared-region0-event-grid-domain/topics/tenant1-20221110154559", 
    "subject": "", 
    "data": { 
      "validationCode": "6E513A74-CE5E-46AA-B66B-48EB9F95A975", 
      "validationUrl": "https://rp-eastus.eventgrid.azure.net:553/eventsubscriptions/webhooksubscription/validate?id=6E513A74-CE5E-46AA-B66B-48EB9F95A975&t=2022-11-10T21:48:52.6581102Z&apiVersion=2021-12-01&token=bN8yuijCceTsWxqoLGstb8%2bh4Go0t1yPbGX%2bZKs95SY%3d" 
    }, 
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent", 
    "eventTime": "2022-11-10T21:48:52.6581102Z", 
    "metadataVersion": "1", 
    "dataVersion": "2" 
  } 
] [

Response options to Endpoint Validation Events

Upon receipt of the Event Validation Event message to the Endpoint URL, a response is required to complete the validation. The following are available options for responding:

• Synchronous handshake: Upon receiving the Endpoint Validation Event, include within the HTTP response the validationCode property and the value which is received in the event. See example above.
• Asynchronous handshake: Perform an HTTP GET request to the validationURL received in the event. See example above.

Note: The provided URL is valid for 5 minutes.

For more information, see WebHook event delivery - Azure Event Grid | Microsoft Learn.

Example event

The following is an example of a Change Notification Event sent from Azure to the Endpoint URL.

In the example, Person/529354ca-bd4a-4b47-95a2-7a83957e00c3 and Person.Created are placeholders for the Subject and Event Types values defined in the Change Notification Event Matrix table.

[ 
  { 
    "id": "4b79fa6f-072f-4e20-81f7-3bf76165ff46", 
    "subject": "Person/529354ca-bd4a-4b47-95a2-7a83957e00c3", 
    "data": "", 
    "eventType": "Person.Created", 
    "dataVersion": "1.0", 
    "metadataVersion": "1", 
    "eventTime": "2022-12-06T22:29:07.2570329Z", 
    "topic": "subscriptions/0ea11a68-4102-467a-9b0f-0637a0f176e0/resourceGroups/shared-region0-rg/providers/Microsoft.EventGrid/domains/shared-region0-event-grid-domain/topics/Tenant1-20221206162705" 
  } 
] 

Change Notification event matrix

The table provides information about which events are supported by Change Notifications. The table contains the following columns:

• Event type – The type of changes which are supported for the iMIS Entity. Currently the supported types are Created, Updated, Deleted, Cancelled and are formatted the following way: EntityName.Action.
• Subject - Corresponds to an iMIS REST Endpoint where you can perform an HTTP GET to retrieve additional details about the Change Notification event’s Entity.

Table 1: Viewing events supported by Change Notifications

Events supported by Change Notifications
Event type (EntityName.Action)	Subject	Event
CommerceItem.[Purchased]	LegacyOrder/{OrderId}	Purchasing a commerce item.
Event.[Created][Updated][Deleted]	Event/{EventId}	Creating, updating, or deleting an event.
Event Registration.[Created][Updated][Cancelled]	EventRegistrationSummary?EventId={EventId}&PartyId={PartyId}	Creating, updating, or deleting an event registration.
LegacyProductItem.[Created][Updated]	LegacyProductItem/{item_code}	Creating or updating a legacy product item.
Membership.[Joined][Renewed]	LegacyPartyMembership?PartyId={PartyId}	Joining or renewing a membership.
Organization.[Created][Updated]	Organization/{PartyId}	Creating or updating an organization.
{SingleInstancePanelSourceName}. [Created][Updated][Deleted]	{SingleInstancePanelSourceName}/{PartyId}	Creating, updating, or deleting a single-instance panel source data row.
{MutiInstancePanelSourceName}. [Created][Updated][Deleted]	{MultiInstancePanelSourceName}~{PartyId}/{Ordinal}	Creating, updating, or deleting multi-instance panel source data rows.
Party.[Created][Updated]	Party/{PartyId}	Creating or updating a party type.
Person.[Created][Updated]	Person/{PartyId}	Creating or updating a person.
User.[Created][Updated]	User/{UserKey}	Creating or updating a user.

Note: For PanelData entity types, the entity name is also the panel source name. For example, creating a multi-instance panel source named MyMultiInstance means MyMultiInstance is also the EntityName that appears in the Change Notification event.

Enabling the change notifications feature

To enable change notifications, do the following:

1. Go to Settings > Change notifications.
Click to view image



2. In the Webhook subscription area, enter the Endpoint URL. Events are received as HTTP requests, and the Endpoint URL is used to receive events tracked by Change Notifications. An Endpoint URL is required to use Change Notifications.
3. (optional) Define Headers to be included with the request that is sent to the Endpoint URL. A header is a field of an HTTP request or response that passes additional context and metadata about the request or response. Headers may be used as a security measure to identify authorized requests. Do the following to define headers:
   • Select Add header.
   • Enter a Header Name and Value. The Header Name must be unique and only contain alpha-numeric characters and/or en dashes ( - ).
4. Click Verify. If successful, a green status message displays. If unsuccessful, a red error message displays. In order to enable Change notifications, the Endpoint URL must be verified.
5. Upon receipt of the Event Validation Event message to the Endpoint URL, a response is required to complete the validation. See Response options to Endpoint Validation Events.
6. Enable the Enable change notifications option.

Note: Any changes to the Endpoint URL and/or Headers will trigger, upon Verify and Save, an Endpoint Validation Event to the endpoint URL.

Note: Change Notifications are not logged in iMIS. Events are received by the Endpoint URL when the Enable change notifications setting is enabled.