Events

What are Events?

Events are distinct actions performed within MyPreferences. They serve as triggers to notify external systems about specific activities or changes. Events provide real-time information to keep systems informed and enable integration with other tools and services through webhooks.

An action may be system initiated or user initiated. For instance, it could involve updating the status of a consent or simply switching the IsMobile status on a phone number. These actions also encompass automated tasks executed by the system, such as propagating preferences and consents, as well as recording opt-outs triggered via the Status Manager integration.

An event is synonymous with an Event Type, serving as a clear indicator of the type of action that occurred.

Each event type is associated with an entity. An Entity represents an object which supports one or more event types. For example, the Preference entity supports the following event types.

• preference.added
• preference.updated
• preference.archived

Types of Events

Actions performed on profiles are referred to as Data Events, whereas actions performed exclusively on configuration objects to update, remove or modify configuration settings are referred to as Configuration Events. Currently, MyPreferences only supports data events and offers a wide range of events that cover various interactions and activities within the platform.

The following list highlights all the Data events supported by MyPreferences.

Subscribing to Events

To receive notifications about specific events, MyPreferences clients can subscribe to one or more event types of interest. This involves setting up a webbook subscription, which allows MyPreferences to send event data as an HTTP POST request to an external endpoint that you specify in your subscription request. Click here to access the Create Subscriptions API.

Authentication

Authentication is crucial to ensure the security and integrity of webbook interactions. MyPreferences webhooks support signature validation that allows receiving endpoints to validate webhook's authenticity, i.e., verify that the data is being posted by MyPreferences. Applications receiving event notifications shall provide a secret key which is configurable on all MyPreferences accounts.

All webhook notifications except the initial validation handshake message include a MyPreferences-Webhook header which contains two parameters, Timestamp and Signature.

The Timestamp parameter is part of the header and is also used when generating the signature. Therefore, during signature validation by the receiving system, any modification to the Timestamp field should result in the rejection of the POST request. The issued Timestamp field is a valid ISO8601 formatted timestamp.

The Signature parameter is generated using a hash-based message authentication code (HMAC) using SHA2 -512. The hash signature is included in the request (authorization) header on each POST request delivered by the webhook.

These parameters are generated and included each time an event is dispatched to a receiving endpoint. In situations where the event is retried due to a failure, a new signature and timestamp is generated for each new attempt.

"WebhookSignature": "Timestamp:2025-07-29T16:47:05Z Signature:7TioN/SDE46JWvF1OHc9VQuQ+j/hv8UQugoRhP+eGLXp6xrZzS0hkanuhmWB+uCfCYTyXd9Oa5rk/jWgbrWWrw==" 

The ClientId, EventsClientSignatureUserId, Timestamp, and a Hashkey are used to construct a SHA512 HTMAC hash. This is similar to generating a hash using the custom authorization scheme to access the MyPreferences REST API. Your receiving application consuming the webhooks is expected to extract the timestamp from the header and use the ClientId, EventsClientSignatureUserId, and Hashkey to reconstruct the signature using SHA512. Your re-computed signature (converted to UTF-8 bytes and then to BASE64) must match the Signature included in the header. If it doesn't, the message must be considered as altered and should be rejected.

Initial Handshake

For all webhook subscriptions, the receiving application needs to participate in a validation handshake. Once the subscription is created, MyPreferences will issue a unique token to the receiving URL before any actual data is delivered. The schema of this event is similar to an actual data event and is shown below.

The data portion of this event includes a validationCode property. Your application verifies that the validation request is for an expected event subscription, and returns the validation code in the response synchronously. Once the handshake is established, your endpoint is authenticated, and it can continue receiving webhook notifications without needing to repeat the token exchange. This ensures secure and seamless communication between MyPreferences and your receiving application.

{
  "data": {
    "validationCode": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B",
    "validationUrl": "https://rp-eastus.eventgrid.azure.net:553/eventsubscriptions/53286-1-7f396aa65cda44338b7763091cc02608-221/validate?id=056C6FF4-3929-42AC-8E94-C6E021FD1C7B&t=2024-07-24T14:09:00.9068770Z&apiVersion=2022-06-15&token=mUTqCc6C6t30ij3vEictNyEP%2baZlJ0cqe8RgeqB%2fo74%3d"
  },
  "dataVersion": "2",
  "eventTime": "2024-07-24T14:09:00.9069218Z",
  "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
  "id": "dfd3c295-0a8b-43c8-be7f-bee71f9842e9",
  "metadataVersion": "1",
  "subject": "",
  "topic": "/subscriptions/1ba4431b-6125-4da0-b908-a890a2e39206/resourceGroups/rgroupdnc29/providers/microsoft.eventgrid/domains/eventgriddomainstaging01/topics/53286-1-7f396aa65cda44338b7763091cc02608"
} 

To prove endpoint ownership, send back the validation code in the validationResponse property as shown below:

{
  "validationResponse": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B056C6FF4-3929-42AC-8E94-C6E021FD1C7B"
} 

You must return an HTTP 200-OK response status code. 202-Accepted isn't recognized as a valid response. The HTTP request must complete within 30 seconds. If the operation doesn't finish within 30 seconds, it will be canceled and can be reattempted after 5 seconds. If all the attempts fail, it will be treated as validation handshake error.

Asynchronous handshake

If you cannot return the validationCode in your response synchronously, a validationUrl property is also included in the data portion of the subscription validation event. To complete the handshake, find that URL in the event data and do a GET request to it. You can use either a REST client or your web browser.

The provided URL is valid for 5 minutes. During that time, the provisioning state of the event subscription is AwaitingManualAction. If you don't complete the manual validation within 5 minutes, the provisioning state is set to Failed. You'll have to create the event subscription again before starting the manual validation.

This method of authentication also requires the webhook endpoint to provide an HTTP status code of 200. This confirms the acceptance of the POST request for the validation event, which is a prerequisite before transitioning into manual validation mode. If the endpoint returns a 200 status code but fails to provide a validation response in a synchronous manner, the system will switch to manual validation mode. Furthermore, if a GET request is made to the validation URL within a 5-minute timeframe, the validation handshake is deemed successful.

Your application's readiness to manage and return the validation code suggests that you've set up the event subscription and are ready to receive events.

Securing Events with mTLS

Events support Mutual Transport Layer Security (mTLS) which brings an extra layer of security between our system and the clients receiving the webhook notifications. With mTLS, both the webhook consumer (receiving systems subscribed to our webhooks) and the webhook producer (our server) engage in mutual authentication, establishing a secure and efficient communication channel. mTLS also ensures data integrity protecting sensitive data from unauthorized access and tampering.

Your receiving endpoint must be setup to handle mTLS, including initiating the validation handshake. mTLS authentication relies on digital certificates, therefore, clients must obtain digital certificates from a trusted Certificate Authority (CA) or an internal PKI (Public Key Infrastructure) before the handshake process.

To enable mTLS support, you must collaborate closely with our support team and follow the steps listed below.

Generate Client Certificate: Obtain a digital certificate for your receiving endpoint from a trusted Certificate Authority (CA). Ensure that the certificate includes the necessary identifying information and is signed by a trusted CA.

Webhook endpoint configuration: Configure your receiving endpoint to present its certificate to the server during the handshake process.

MyPreferences Configuration: The MyPreferences Support team will configure your client certificate on our server for authentication.

Trust Server Certificate: Ensure that your receiving endpoint trusts the certificate provided by MyPreferences.

Test Connection: Test the connection between your receiving endpoint and MyPreferences to ensure that mTLS authentication is setup and functioning correctly.

You will closely collaborate with our support team throughout the setup procedures. Should you encounter any issues during the setup process, reach out to our support team for assistance.

Receiving Events

The system expects a HTTP 200-OK response from the webhook URL. Any other response codes (3xx, 4xx, or 5xx) are treated as a failure. Once the handshake is established, no content is required in the response body from the target webhook URL.

The MaxConcurrentRequests and Durationsettings manage the events throughput. The MaxConcurrentRequests determines how many events the event delivery service will try to send in one cycle. The Duration determines how long it will wait between each cycle. Though we do not track the exact amount of events that are generated via the event handler service, it is a precautionary measure to maintain optimal delivery rate and frequency.

Creating and managing event subscriptions

MyPreferences provides a set of Subscription APIs to manage webhook subscriptions:

• POST /subscriptions: Create a new subscription by specifying the desired event types and the target webhook URL.
• GET /subscriptions: Retrieve a list of active subscriptions along with their details.
• PUT /subscriptions/{subscription_id}: Update the configuration of an existing subscription, such as updating the list of event types.
• DELETE /subscriptions/{subscription_id}: Deactivate and remove a subscription, stopping notifications for selected event types.

Event Payload

When an event occurs, MyPreferences sends an HTTP POST request to the subscribed endpoint. The payload contains information about the event, including its type, timestamp, and relevant data associated with the event.

Subscription Payload

The subscription payload includes details about the subscription itself, such as the ID, webhook URL, and subscribed event types. This information helps identify the source of incoming requests and the event types being monitored.

Failures and retries

MyPreferences expects a 200-OK response to mark the request as success. All configured webhook URLs shall return a 200-OK response immediately upon receiving the event.

The system waits 30 seconds for a response after delivering a message. After 30 seconds, if the endpoint hasn’t responded, the message is queued for retry. It uses an exponential backoff retry policy for event delivery. The retries are performed based on the following schedule on a best effort basis:

If the endpoint responds within three minutes, the message distribution service attempts to remove the event from the retry queue on a best effort basis, but duplicates may still be received. It adds a small randomization to all retry steps and may opportunistically skip certain retries if an endpoint is consistently unhealthy, down for a long period, or appears to be overwhelmed.

The service supports the following retry configurations. An event is dropped if either of the limits of the retry policy is reached.

10 seconds
30 seconds
1 minute
5 minutes
10 minutes
30 minutes
1 hour
3 hours 

Event time-to-live (TTL): The value must be an integer between 1 and 240. The default value is 240 minutes.

An event is sent to the dead letter queue if it is not delivered within the time-to-live period or the number of retries limit is reached. If we receive a 400 (Bad Request) or 413 (Request Entity Too Large) response code, the event is immediately scheduled for dead-lettering. These response codes indicate delivery of the event will never succeed.

The time-to-live expiration is checked only at the next scheduled delivery attempt. So, even if time-to-live expires before the next scheduled delivery attempt, event expiry is checked only at the time of the next delivery and then subsequently dead-lettered.

Once the event is sent to the dead-letter queue, the event delivery is abandoned. Our event failure notification service picks up the record from the queue, extracts the details, including the appropriate http status returned, failure reason. and sends out email alerts to the list of recipients configured to receive event failure alerts. The alerts are sent based on the alert criteria configuration described below.

Alerts

Alerts are not sent during the retry process. Once the event is sent to the dead-letter queue, the alert notifications are triggered based on the settings detailed below.

Alert Frequency: This represents the rate at which alerts are generated within a specific duration. It indicates how often an alert is triggered based on the occurrence of an event that failed to deliver. It contains the following settings:

• Alert Frequency (Min): This setting defines the minimum time between alerts. It ensures that once an alert is triggered, there is a designated gap before another alert can be generated. This prevents MyPreferences from generating excessive alerts and creating unnecessary noise. Default setting is 5 minutes. It supports values more than 0.
• Alert Frequency (Max): This setting defines the maximum rate at which alerts are triggered when the webhook fails. For example, if the max frequency is set to 5 minutes, the system will not generate more than one alert every 5 minutes. Default setting is 30 minutes.

Alert Threshold: This represents the count/number of errors or failures that must occur within a designated time period to trigger an alert. It ensures that only significant issues are flagged for immediate attention. It works in conjunction with “Alert Frequency” settings. It contains the following settings:

• Alert Threshold (Min): This is the minimum number of errors/failures that must occur within a designated time-frame to trigger an alert. It works in conjunction with “Alert Frequency”. Only values greater than "0" are supported for this setting. The default value is set to "1". Min value cannot exceed "100". For example, if it is is set to 5 consecutive failures, an alert will be generated only if the webhook fails to send notifications for 5 consecutive attempts.
• Alert Threshold (Max): This is the maximum allowable number of errors/failures within a defined duration before generating an alert. It helps prevent excessive alerting for less severe issues. It sets the maximum number of failures that are allowed before the system stops generating alerts. Works in conjunction with “Alert Frequency”. Only values greater than "5" are supported. The default value is set to "15". Max value cannot exceed "1000".

Usage and Recommendations

Utilizing webhooks effectively requires careful consideration of event selection and implementing best practices. One approach is to selectively subscribe to specific event types that align with your needs. For instance, subscribing to profile.created or profile.replaced event types can be advantageous as they provide comprehensive profile information by returning the entire profile. By choosing these events, you can streamline data retrieval while reducing unnecessary traffic.

The profile.replaced event is specifically generated when a PUT operation is performed to overwrite the profile. MyPreferences will not send any other events when profile.created or profile.replaced events are triggered.

To receive profile update notifications, subscribe to the profile.updated event to be alerted when a profile changes, or to the profile.updatedfull event to receive the complete profile data in the event payload.

When subscribing to Preference events, you can specify the Filters for which you want to receive events. You can specify AllFilters to receive events for all filters.

When subscribing to Consent events, you can specify the Consent Types for which you want to receive events. You can specify AllConsents to receive events for all consent types configured in your MyPreferences account. The same applies to Groups , Contacts, and Custom Fields.

Events for Standard Fields and Tags are applied globally across all profiles. For example, if you subscribe to standardfield.firstname.updated event type, a webhook notification is triggered anytime the first name field gets updated on any active profile.

Multiple actions = Multiple events

Often times, a simple operation on a profile may trigger multiple events. For example, a user adds an email address to their profile, updates a communication preference, and grants a consent. This action will result in the following event types being generated, each indicating the exact operation performed on customer's data.

• profile.updated
• contacts.email.added
• preference.added
• consent.filterassociation.created

Each event represents an independent action. You must pay close attention to elements such as OriginalEventTime, EventTime, ProfileId, and associated data to correctly sequence the updates made to a user's profile.

The OriginalEventTime property denotes the date and time when the event occurred. The EventTime property represents the date and time when the event was queued for distribution. These dates are designed to help you determine the processing order as well as identify the lag between the time it took to receive the event from its initial capture.

The Data property includes the updated customer data associated with the event and makes it available for immediate use. The EventType property specifies the actual event.

Tracking Changes with Previous Data Collection

Webhook payloads for Standard Fields, Custom Fields, Customer Types, Contacts, and AlternateIds include both the current and previous values of updated fields. Alongside the Data object, a PreviousData object is also returned. This allows for precise change tracking, auditing, and improved synchronization by clearly showing what has changed.

By leveraging MyPreferences Events and Subscriptions framework, clients can stay informed about crucial activities within the platform and seamlessly integrate MyPreferences with external systems to enhance their workflow and decision-making processes.