Azure managed applications with notifications

Azure managed application notifications allow publishers to automate actions based on lifecycle events of the managed application instances. Publishers can specify a custom notification webhook endpoint to receive event notifications about new and existing managed application instances. Publishers can set up custom workflows at the time of application provisioning, updates, and deletion.

Getting started

To start receiving managed application notifications, create a public HTTPS endpoint. Specify the endpoint when you publish the service catalog application definition or Microsoft Azure Marketplace offer.

Here are the recommended steps to get started quickly:

  1. Create a public HTTPS endpoint that logs the incoming POST requests and returns 200 OK.
  2. Add the endpoint to the service catalog application definition or Azure Marketplace offer as explained later in this article.
  3. Create a managed application instance that references the application definition or Azure Marketplace offer.
  4. Validate that the notifications are being received.
  5. Enable authorization as explained in the Endpoint authentication section of this article.
  6. Follow the instructions in the Notification schema section of this article to parse the notification requests and implement your business logic based on the notification.

Add service catalog application definition notifications

The following examples show how to add a notification endpoint URI using the portal or REST API.

Azure portal

To get started, see Quickstart: Create and publish an Azure Managed Application definition.

Screenshot of the Azure portal that shows a service catalog managed application definition and the notification endpoint.

REST API

Note

You can only supply one endpoint in the notificationEndpoints property of the managed application definition.

{
  "properties": {
    "isEnabled": true,
    "lockLevel": "ReadOnly",
    "displayName": "Sample Application Definition",
    "description": "Notification-enabled application definition.",
    "notificationPolicy": {
      "notificationEndpoints": [
        {
            "uri": "https://isv.azurewebsites.net:1214?sig=unique_token"
        }
      ]
    },
    "authorizations": [
      {
        "principalId": "d6b7fbd3-4d99-43fe-8a7a-f13aef11dc18",
        "roleDefinitionId": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
      },
    ...

Add Azure Marketplace managed application notifications

For more information, see Create an Azure application offer.

Screenshot of Azure Marketplace managed application notifications in the Azure portal.

Event triggers

The following table describes all the possible combinations of eventType and provisioningState and their triggers:

EventType ProvisioningState Trigger for notification
PUT Accepted Managed resource group was created and projected successfully after application PUT (before the deployment inside the managed resource group is kicked off).
PUT Succeeded Full provisioning of the managed application succeeded after a PUT.
PUT Failed Failure of PUT of application instance provisioning at any point.
PATCH Succeeded After a successful PATCH on the managed application instance to update tags, just-in-time (JIT) access policy, or managed identity.
DELETE Deleting As soon as the user initiates a DELETE of a managed app instance.
DELETE Deleted After the full and successful deletion of the managed application.
DELETE Failed After any error during the deprovisioning process that blocks the deletion.

Notification schema

When you create your webhook endpoint to handle notifications, you need to parse the payload to get important properties to then act upon the notification. Service catalog and Azure Marketplace managed application notifications provide many of the same properties, but there are some differences. The applicationDefinitionId property only applies to service catalog. The billingDetails and plan properties only apply to Azure Marketplace.

Azure appends /resource to the notification endpoint URI you provided in the managed application definition. The webhook endpoint must be able to handle notifications on the /resource URI. For example, if you provided a notification endpoint URI like https://fabrikam.com then the webhook endpoint URI is https://fabrikam.com/resource.

Service catalog application notification schema

The following sample shows a service catalog notification after the successful provisioning of a managed application instance.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>"
}

If provisioning fails, a notification with the error details is sent to the specified endpoint.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>",
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}

Azure Marketplace application notification schema

The following sample shows a service catalog notification after the successful provisioning of a managed application instance.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  }
}

If provisioning fails, a notification with the error details is sent to the specified endpoint.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  },
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}
Property Description
eventType The type of event that triggered the notification. For example, PUT, PATCH, DELETE.
applicationId The fully qualified resource identifier of the managed application for which the notification was triggered.
eventTime The timestamp of the event that triggered the notification. Date and time in UTC ISO 8601 format.
provisioningState The provisioning state of the managed application instance. For example, Succeeded, Failed, Deleting, Deleted.
applicationDefinitionId Specified only for service catalog managed applications. Represents the fully qualified resource identifier of the application definition for which the managed application instance was provisioned.
billingDetails Specified only for Azure Marketplace managed applications. The billing details of the managed application instance. Contains the resourceUsageId that you can use to query Azure Marketplace for usage details.
plan Specified only for Azure Marketplace managed applications. Represents the publisher, offer, SKU, and version of the managed application instance.
error Specified only when the provisioningState is Failed. Contains the error code, message, and details of the issue that caused the failure.

Endpoint authentication

To secure the webhook endpoint and ensure the authenticity of the notification:

  1. Provide a query parameter on top of the webhook URI, like this: https://your-endpoint.com?sig=Guid. With each notification, check that the query parameter sig has the expected value Guid.
  2. Issue a GET on the managed application instance by using applicationId. Validate that the provisioningState matches the provisioningState of the notification to ensure consistency.

Notification retries

The managed application notification service expects a 200 OK response from the webhook endpoint to the notification. The notification service retries if the webhook endpoint returns an HTTP error code greater than or equal to 500, it returns an error code of 429, or if the endpoint is temporarily unreachable. If the webhook endpoint doesn't become available within 10 hours, the notification message is dropped, and the retries stop.