Setting Up a Secure Webhook in an Azure Monitor Action Group
When configuring an Action Group in Azure Monitor, one of the most powerful notification options is a secure webhook. This allows you to send alerts to an external endpoint with an authentication token, ensuring that only authorized services can process the alerts. However, setting this up can be a bit confusing—especially when dealing with app registrations, service principals, and roles. This guide simplifies the process by breaking it down into clear steps. Please check the official documentation here. The PowerShell (PS) commands I use below have been derived from the document, but I am using the Azure Portal to create the AppRole. Prerequisites Before diving in, make sure you have the following: PowerShell (PS) with the Microsoft.Graph module installed Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force Run this command to connect with the proper scope to MsGraph: Connect-MgGraph -Scopes “Application.ReadWrite.All” -TenantId $yourTenantId The Azns AAD Webhook Service Principal created in your Microsoft Entra tenant. This service principal is critical, as it allows Azure Monitor to authenticate when calling your webhook. You’ll need to ensure this principal is in your tenant and assign the necessary role(s) to it. This principal can be found in the Microsoft Entra tenant (This is different from your Entra tenant). When you run the following command to create this service principal it will create this as a first-party Microsoft application in your tenant. For more info on these apps in your tenant please check out this document. To check and see if you have this service principal in your tenant. Notice we are checking for a specific id, it must be this id to work correctly. You can run the following PS command: Get-MgServicePrincipal -Filter "appId eq '461e8683-5575-4561-ac7f-899cc907d62a'" If the command returns nothing, you can create it by running this PS command: New-MgServicePrincipal -AppId 461e8683-5575-4561-ac7f-899cc907d62a Step 1: Create an App Registration Now that you have all the pre-requisites, the first step is to register an application in Microsoft Entra ID. Configure this to expose application permissions. How to create the App Registration: Navigate to Microsoft Entra ID in the Azure Portal Click on App registrations → New registration Provide a Name (e.g., SecureWebhookApp) Click Register Important Notes: You must explicitly assign yourself as an owner of the app registration. This ensures that it appears in the Azure Portal UI when selecting app registrations for your webhook setup. Step 2: Add Application ID URI An Application ID URI is required to uniquely identify the web API that the webhook will use for authentication. How to set the Application ID URI: In your App Registration, go to Expose an API Click the Add link next to the Application ID URI This will open up the Edit application ID URI blade on the right Use the default, or enter a unique URI Click Save It will look something like this: This step is crucial because the Action Group will not allow you to save your secure webhook giving you and error like this: Step 3: Create an App Role for the App Registration Next, we need to define an application role that will be used for authentication. This role is required so that the ‘Azns AAD Webhook’ Service Principal can obtain a token with the appropriate permissions. We will join this role to the service principal in a later step. How to create an App Role: In your App Registration, go to the App roles section Click Create app role Set the Display name and Value (e.g., App.ActionGroupSecureWebhook) Set the Allowed member type to Application Add a Description Step 4: Assigning the ‘Azns AAD Webhook’ Service Principal to the Role The next step is to use the following PS command to assign the role to the ‘Azns AAD Webhook’ Service Principal. This functionality is not currently available in the portal which is why you have to do it via the MsGraph PS command. How to the App Role: Run the following command in PS New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $myActionGroupServicePrincipal.Id -PrincipalId $myActionGroupServicePrincipal.Id -AppRoleId $myAppRoleId -ResourceId $myAppRegistrationId Please check out the full script that I use to connect to MsGraph, get all the ids and create the Service Principal and the role assignment. You will need to fill in your own values for $myTenantId, $myMicrosoftEntraAppRegistrationObjectId, and $myActionGroupRoleName You can confirm this by doing the following: Open up your App Registration -> Overview In the ‘Essentials’ section you should see a place for ‘Managed application in local directory’, that will have a link that will take you to the ‘Enterprise Application’ Once you are in the ‘Enterprise Application’, go to Manage -> Users and groups and you should see something like this. It shows you that you have successfully assigned the app role you created to the ‘Azns AAD Webhook’ Service Principal: Step 5: Create the Secure Webhook Finally, we are ready to create the Secure Webhook from the Action Group Edit page. How to create the Secure Webhook: Navigate to the Action Group you want to add the secure webhook to Azure Monitor -> Alerts -> Action groups Select the Action group you want to edit and hit the Edit button Find the actions section and under ‘Action type’, select Secure Webhook from the dropdown: That will open up a blade on the right where you will need to select the Object ID of the app registration you created above (this is where it will only show up if you are the owner of that app registration) Select the object Id If you just created the app registration, you may need to wait several minutes for the system to synchronize and process the necessary updates. Fill in the webhook uri Choose if you want the ‘Common alert schema’ or not Fill out the name of the webhook back under the Actions section. Hit ‘Save changes’ button Now you can test your action group and confirm that the bearer token is passed with the request, and that the app role was added to the token. To do this I usually just hit the ‘Test action group’ button at the top next to the ‘Save changes’ button. Then that will bring up the Test blade. Select a sample alert type and hit the test button. The webhook I’m using is a custom Azure Function that is logging out the headers so that I can verify the Bearer token was passed in. If you would like to see this code it is available at this repo. Here is what the log output looks like: Taking a closer look at the token you can see that it included the role and the app id of the ‘Azns AAD Webhook’ Service Principal: How It Works Once the setup is complete, the Action Group will: Request a token from Microsoft Entra ID using the app role you've created Include the token in the Authorization header of the webhook request This ensures that the receiving system can validate the request and only process alerts from authorized sources. Wrapping Up Setting up a secure webhook for Azure Monitor Action Groups might seem complex, but by following these steps, you can ensure that your alerts are sent securely and authenticated. By leveraging Microsoft Entra ID, app roles, and service principals, you’re adding a layer of security to your webhook integrations—protecting sensitive alert data from unauthorized access. Would love to hear your thoughts—have you implemented secure webhooks before? Let me know in the comments!
