Getting Started - WebHooks

You can register a WebHook with Software Potential to receive notifications of various licensing events. When an event occurs the Software Potential service will send a notification to all WebHooks registered for that event. For each registered WebHook, Software Potential will attempt to send the notification a number of times before giving up.

You can process the notification data appropriately e.g. associate it with a customer in a  CRM/ERP system, trigger an email notification to the end customer etc.  If you wish you can also use the notification data to retrieve further detailed information from the Software Potential service e.g. for a license Issue/Reissue event you can retrieved detailed license and/or customer data.

For more information on WebHooks and event notifications see https://docs.microsoft.com/en-ie/aspnet/webhooks/

Action Notifications

As of 30 March 2017 you can register for notifications of the following actions:

• License Issue
• License Reissue
• License Update
• License Assign
• License Unassign
• License Activation
• License Reactivation
• License Deactivation

License Issue/Reissue Notification Data

License Issue and Reissue notifications contain the following data:

• Action: -  LicenseIssue / LicenseReissue
• LicenseRefId: - unique identifier of the license issued/reissued; can be used to retrieve license data from Software Potential service
• Activation Key: - the Activation Key of the license isssued/reissued
• CustomerId: - unique identifier of the customer (if any) to whom the license has been assigned

License Update Notification Data

License update notifications contain the following data:

• Action: - LicenseUpdate
• LicenseRefId: - unique identifier of the license updated; can be used to retrieve license data from Software Potential service

License Assign/Unassign Notification Data

License assign/unassign notifications contain the following data:

• Action: - LicenseAssigned / LicenseUnassigned
• LicenseRefId: - unique identifier of the license assigned/unassigned; can be used to retrieve license data from Software Potential service
• CustomerId: - unique identifier of the customer from whom the license has been unassigned or to whom the license has been assigned.

License Activation Notification Data

License activation notifications contain the following data:

• Action - Activation
• LicenseRefId:- unique identifier of the license activated; can be used to retrieve license data from Software Potential service
• ActivationKey: - the Activation Key of the license activated
• ActivationTime: - the time of the license activation (DateTime)
• DeviceId: - the unique identifier of the device on which the license was activated
• DeviceLabel: - the label of the device on which the license was activated (if populated)
• IsEvaluation: - indicates if the license activated was a trial (evaluation) license

License Reactivation Notification Data

License reactivation notifications contain the following data:

• Action: - Reactivation
• LicenseRefId:- unique identifier of the license reactivated; can be used to retrieve license data from Software Potential service
• ActivationKey: - the Activation Key of the license reactivated
• ActivationTime: - the time of the license activation (DateTime)
• DeviceId: - the unique identifier of the device on which the license was reactivated
• DeviceLabel: - the label of the device on which the license was reactivated (if populated)
• IsEvaluation: - indicates if the license reactivated was a trial (evaluation) license

License Deactivation Notification Data

License deactivation notifications contain the following data:

• Activation: - Deactivation
• LicenseRefId:- unique identifier of the license deactivated; can be used to retrieve license data from Software Potential service
• DeviceId: - the unique identifier of the device on which the license was deactivated

Build and Deploy WebHook Listener Application

You must build and deploy a publicly addressable WebHook listener application to receive the notifications sent by Software Potential. To do this using ASP.NET Web API application: 

Install NuGet Packages

Intall Microsoft.AspNet.WebHooks.Receivers.Custom NuGet package

Initialize Custom WebHooks

Add config.InitializeReceiveCustomWebHooks(); at the end of the WebApiConfig class in the WebApiConfig.cs file

Add NotificationModel for each event

Add WebHookNotification class and an EventModel class for each event subscribed to.

The following is an example WebHookNotification and EventModel for the license Issue and Reissue Events:

    public class WebHookNotification
    {
        public Guid Id { get; set; }
        public int Attempt { get; set; }
        public IssueEventModel[] Notifications { get; set; }
    }

    public class IssueNotificationModel
    {
        public string Action { get; set; }
        public Guid LicenseRefId { get; set; }
        public string ActivationKey { get; set; }
        public Guid? CustomerId { get; set; }
    }

Add a Handler for the notifications

Add a handler that filters for the action associated with the notification.

The following example handles the LicenseIssue and LicenseReissue notifications, and stores the notification in an in-memory repository:

    public class Handler : WebHookHandler
    {
        public override Task ExecuteAsync( string receiver, WebHookHandlerContext context )
        {
            string action = context.Actions.First();
            if ( action == "LicenseIssue" || action == "LicenseReissue" )
            {
                var data = context.GetDataOrDefault();
                InMemoryLicenseNotificationRepository.LicenseNotifications.AddRange( data.Notifications.Where( x => x != null ) );
            }
            return Task.FromResult( true );
        }
    }

Add Shared Secret to Webconfig

Generate a shared secret that will be used to secure communications with your WebHook listener.  This must be between 32 and 64 characters long.

Add the shared secret to the appconfig file:

  <appSettings>
    <add key="MS_WebHookReceiverSecret_Custom" value="INSERT WEBHOOK SHARED SECRET HERE" />
  <appSettings>

Register A WebHook

To register a WebHook:

• Select Develop → Create WebHooks in the main navigation
• Select the actions to which you wish to subscribe
• Register the notification url http://<yourdomain>/<IssueNotifciation>/api/webhooks/incoming/custom
NOTE: The URL must be publicly accessible in order for the Software Potential service to contact it with a notification
• Enter the WebHook shared secret you generated earlier (must be between 32 and 64 characters)
  NOTE: Keep track of your shared secret using a password manager. This secret is your responsibility and cannot be retrieved from the Software Potential service.

Pause A WebHook

If necessary you can temporarily pause sending of notifications.  To pause a WebHook:

• Select Develop → Manage WebHooks in the main navigation
• Select the WebHook to be paused from the list of registered WebHooks
• Check the Paused checkbox and click Save button.

Software potential will not send any notifications to this WebHook until such time as it is resumed.

To resume a paused WebHook, select the WebHook in the list of registered WebHooks, uncheck the Paused checkbox and click Save button.

Webhook Availability

It is the vendor's responsibility to ensure high availability of webhook receivers registered to receive Software Potential event notifications. It is recommended that vendors implement active monitoring of all webhook receivers' availability/performance so that outages/downtime can be minimized.

Webhook Retry Policy

When Software Potential is unable to deliver a notification to an enabled but unavailable webhook, it will retry the failed notification for a period of 24 hours. At the end of this retry period, if the notification still cannot be delivered, it will be deleted.

It is also important to know that no record is kept of these deleted notifications and therefore a vendor 's webhook will need to deal with "out of sequence" notifications that arrive when the webhook has been re-enabled after being unavailable for more than 24hrs.

Auto disablement of Unavailable Webhooks

If Software Potential detects that a registered, an enabled webhook is unavailable for an extended period of time, the webhook may be automatically disabled to prevent repeated retries over an extended period of time. This is to deal with registered webhooks that may no longer be active but have not been disabled by a vendor.

Disabled Webhooks

Vendors have the option to disable a registered webhook in Software Potential. Notifications will NOT be sent while a webhook is disabled. It is also important to know that no record is kept of these unsent/missing notifications and therefore these will NOT be resent when the webhook is re-enabled. Therefore vendor webhooks need to deal with "out of sequence" notifications that arrive when a webhook has been re-enabled e.g. an update notification for a license that was issued while the webhook was disabled.