Using Webhook with Azure Runbooks and PowerShell

Title
Using Webhook with Azure Runbooks and PowerShell
URL Name
Using-Webhook-with-Azure-Runbooks-and-PowerShell

Question
Answer

Runbooks are available in Azure tenants to easily run additional PowerShell scripts that are triggered by a webhook.
Webhooks are used in a variety of places in ProvisionPoint to allow custom configuration before or after provisioning, as a manual action or lifecycle action, as a Service type.

    This article will give guidance on how to setup a Runbook and link it to ProvisionPoint

    Setup in Azure

    • A Subscription in Azure
    • A Resource Group in Azure
    • An 'Automation account in Azure 
    • Import Modules into the Automation account:
      • Az,Accounts, AZ.Automation, AZ.ManagedServiceIdentity, any others required for the task you will be performing. 
    • A Managed Identity in Azure with appropriate permissions assigned (for example Microsoft Graph API or SharePoint API)
    • Enable the Managed Identity in the Automation Account

    A Tutorial is available from Microsoft to assist: Create PowerShell Runbook Using Managed Identity in Azure Automation | Microsoft Learn 
    This tutorial will setup a virtual machine in the script, this is unlikely to be your end result.

    Manage runbooks in Azure Automation | Microsoft Learn

    Create a Runbook

    This article will presume you have the Azure setup completed and you have the correct permissions defined.

    Multiple Runbooks can be created in a single Automation account.

    1. Open the Automation Account in Azure
    2. In the side menu, expand 'Process Automation' 
    3. Select Runbooks > Create a runbook
      1. Name (no spaces)
      2. Type = PowerShell
      3. Version = 7.2
      4. Description
      5. Tags (optional) are name/value pairs that enable you to categorize resources and view consolidated billing by applying the same tag to multiple resources and resource groups 
    4. Select Review + Create to validate the setup, then click Create

    Create PowerShell code

    Create the PowerShell code you want to apply, ensuring you extract out any relevant data from the ProvisionPoint webhookdata.

    Once complete, Publish the runbook

    Below is an example that will
    • Extract out key data from the ProvisionPoint webhook (SiteUrl)
    • Connect to PnP Online and disabled sharing permissions for the Site that is created
    • Use the Managed Identity to authenticate
      • If using User-Assigned Managed Identity, add -ManagedIdentity -ClientId <GUID> to Connect-PnPOnline.
    Param(
    [Parameter(Mandatory = $false)]
    [object]$WebhookData 
)

# Data - extract key data from ProvisionPoint's webhook data
$WebhookData = (ConvertFrom-JSON -InputObject $WebhookData)
Write-Output "WebhookData = $WebhookData"
$data = (ConvertFrom-JSON -InputObject $WebhookData.RequestBody)
$action = $($data.actionDetail)
Write-Output "Action = $action"
$title = $($action.title)
Write-Output "Title = $title"
$SiteURL = $($action.url)
Write-Output "SiteUrl = $SiteURL"


#######################################################################################################################################
try {
    # Ensure PnP.PowerShell module is available
    if (-not (Get-Module -ListAvailable -Name "PnP.PowerShell")) {
        throw "PnP.PowerShell module is not installed in this Automation Account."
    }

    Write-Output "Connecting to $SiteUrl using Managed Identity..."

    # Connect using Managed Identity
    Connect-PnPOnline -Url $SiteUrl -ManagedIdentity

    Write-Output "Connected successfully."

    #Option 1: Disable Sharing permissions settings - Disable Sharing for Non Owners
    Set-PnPSite -Identity $SiteURL -DisableSharingForNonOwners

    Write-Output "Permission update requested."

    # Disconnect session
    Disconnect-PnPOnline
    Write-Output "Disconnected from $SiteUrl."
}
catch {
    Write-Error "Error: $($_.Exception.Message)"
    throw
}

     

       

      Create the Webhook Url

      The Final step is to create the webhook Url that will be added to ProvisionPoint to trigger your runbook.
      1. Expand Resources in the runbook side panel
      2. Select Webhooks then Add Webhook
      3. Name the webhook
      4. Enable
      5. Set an Expiry date - make a note of this to ensure a new webhook is generated before it expires to continue functionality
      6. Copy the URL & store it securely - after creation the webhook url will no longer be visible

      7. Click 'Configure Parameters and Run Settings' button
        1. If your PowerShell states the parameter WebhookData is false > click update
          ProvisionPoint will pass this data through.
        2. If your PowerShell states the parameter WebhookData is true > you will need to define the values > click update
      8. Click Create

       

      Add the Webhook to ProvisionPoint

      • Developer tab in each Service Definition
      • Developer tab in each Action
      • Custom Actions
        • Manually enabled in each Service Definition 
        • In a Stage of a Lifecycle Policy
      • Custom Service Type for new requests

      The developer tab offers PRE or POST webhooks, which will determine when the webhook will be triggered (Before or after provisioning). Custom Actions and Service Types will be triggered when the action is run.

      Click here to read about applying the webhooks to requests and actions

      API & Webhook Output - Additional Information

      SECURTIY, COMPLIANCE & GOVERNANCEProvisionPoint