Webhooks and Azure Automation Runbooks

Azure Automation

Overview

Azure Automation is Microsoft’s cloud-hosted automation solution.  It uses Python or PowerShell based scripts, referred to as runbooks, to launch automation jobs in Azure or on-premises.  These runbooks are started in multiple ways.  The information below details starting automation jobs with a webhook.

Webhook vs. API

To start, let’s go over the difference between a webhook and an API.  Think of a webhook as one-way communication.  Use email as an analogy.  An email is sent with an assumption it gets to the destination, you may get a bounce message if it failed, but there is no way to know if it was received and read by the recipient.  The email has information attached and it may result in some action, that action could be a reply or some other activity by the recipient.

An API, on the other hand, is interactive.  Think of it as a chat service. You address the message to a user and the user will respond to the message based on the information sent.  An API call is similar, information is passed to the API with the expectation of some type of data returned.

Webhook Formatting

Azure Automation runbooks can start with a webhook.  A webhook is a custom URL passed to Azure Automation along with a data payload specific to the runbook.  A runbook starts when a properly formatted HTTP Post message is sent.  There may or may not be a confirmation depending on the runbook.  For example, it could send a confirmation email or log an event.  

The Azure Automation webhook has three parts, the URI, the Request Header and Request Body.  The Webhook Name is also included in the payload of the webhook.

URL – The address containing a security token used to call the Runbook
Request Header – A hash table containing the header information for the webhook
Request Body – Data passed to the runbook.  The data can be a string, JSON or XML.  The runbook must be able to consume the data type sent in the webhook.
Webhook Name – The name of the webhook is passed to the runbook

The runbook examples below are kept simple for the sake of the demonstration.  They use the Azure Automation output stream to display the data passed to the runbooks.  In “real life” this data would be consumed by the runbooks as part of the automation process.  The goal of this exercise is to demonstrate what that data looks like and how it can be used once passed into the runbook from the webhook.

Create Webhook

To begin, create a PowerShell runbook in an Azure Automation account and configure the Webhook.  Leave the runbook blank for now and publish it before the next step.

Create Azure Automation Runbook
Create Azure Automation Runbook
Publish Azure Automation Runbook
Publish Azure Automation Runbook

From the Runbook blade, select Webhooks under Resources and Add Webhook.

Add a Webhook
Add a Webhook

Create the new webhook by entering a name and set it to enabled.  The webhook will expire in a year by default.  Copy and save the webhook URL before finishing.  As noted on the screen, you will not be able to view the webhook URL after clicking OK. 

Create a New Webhook
Create a New Webhook

Leave the Modify run settings as default.  Click Create to create the webhook

Simple Test

Start the first test by updating the runbook with the following code.  Save, and publish the runbook when finished.  This simple code outputs the values sent by the webhook to demonstrate how it is interpreted by the runbook.

param (
    [Parameter (Mandatory = $false)]
    [object] $WebHookData
)
if ($WebHookData){
        Write-Output "The Webhook Header"
    Write-Output $WebHookData.RequestHeader.Message
    # Header message passed as a hashtable 
    Write-Output 'The Webhook Name'
    Write-Output $WebHookData.WebhookName
    # This is the name of the webhook in Azure Automation
    Write-Output 'The Request Body'
    Write-Output $WebHookData.RequestBody
    # Body of the message
}
else {
    Write-Output 'No data received'
}

The code below assembles the webhook and starts the runbook with the post method.  A breakdown of each line is listed below with the complete code at the end of this section.

RequestBody – This is the payload of the message.  The runbook must be written to consume the data sent.

$bodyMsg = @(
     @{ Message="Test Message"}
 )

URI – the URL of the webhook

 $uri = 'https://s1events.azure-automation.net/webhooks?token=y%2bewxa2nN14Boruw3db%2bBfHQy%2fmGxPF7dx9bT7y'

Request Body Conversion – the body has to be converted to text when passed to the runbook

 $body = ConvertTo-Json -InputObject $bodyMsg

RequestHeader – Table containing the header of the message

$header = @{ message = "StartedByTravis"}

Post – The code below posts the webhook and holds the response in the $response variable

$response = Invoke-RestMethod -Method post -Uri $uri -Body $body -Headers $header

The complete code looks like what is shown below.  Update the information, including the $uri value to match your environment.  Run to code to view the output in Azure Automation.

$bodyMsg = @(
     @{ Message="Test Message"}
 )
 $uri = 'https://s1events.azure-automation.net/webhooks?token=y%2bewxa2nN14Boruw3db%2bBfHQy%2fmGxPF7dx9bT7y'
 $body = ConvertTo-Json -InputObject $bodyMsg
 $header = @{ message = "StartedByTravis"}
 $response = Invoke-RestMethod -Method post -Uri $uri -Body $body -Headers $header

Next, go into the job to view the Job Summary.  This area allows you to view the details of the job, including Errors and Warnings if they exist, inputs, outputs, and Logs.  

Webhook Job Summary

Webhook Job Summary

Go to Outputs to see the Output of the job.

Simple Test Output

Simple Test Output

A window similar to the one above shows if successful.  The Output includes the Webhook Header passed to the runbook and the name of the webhook.  The Request Body shows the JSON payload.  This is okay, but it would be better to convert the JSON back to a PowerShell Object for use in the PowerShell Runbook.

Accessing Webhook Data

This example will take the above a step further by first adding a second entry into the Request Body. The runbook will convert the body from JSON to a PowerShell object with the ConvertFrom-JSON command. The runbook outputs the second entry in the request body using $Body.Message[1].  After that, it will output the full request body and lastly, it will use get-member to display the data type.

Update, Save and Publish the code below to the runbook for the next example.

param (
    [Parameter (Mandatory = $false)]
    [object] $WebHookData
)

if ($WebHookData){
    Write-Output "The Webhook Header"
    Write-Output $WebHookData.RequestHeader.Message
    # Header message passed as a hashtable 

    Write-Output 'The Webhook Name'
    Write-Output $WebHookData.WebhookName
    # This is the name of the webhook  in Azure Automation

    $body = ConvertFrom-Json -InputObject $WebHookData.RequestBody
    # Convert the body from JSON

    Write-Output 'The Request Body Second Item'
    Write-Output $body.Message[1]
    # View Message

    Write-Output 'The Full Body'
    Write-Output $body
    # View the full body

    Write-Output 'Body Get Member'
    Write-Output ($body | Get-Member)
    #View the data type
}
else {
    Write-Output 'No data received'
}

Next, run the webhook request with the information below, modified for your environment.

$bodyMsg = @(
     @{ Message="Test Message 1"}
     @{ Message="Test Message 2"}
 )
$URL = 'https://s1events.azure-automation.net/webhooks?token=y%2bewxa2nN14Boruw3db%2bBfHQy%2fmGxPF7dx9bT7y'
 $body = ConvertTo-Json -InputObject $bodyMsg
 $header = @{ message = "StartedByTravis"}
 $response = Invoke-RestMethod -Method post -Uri $URL -Body $body -Headers $header

The output from the above shows the second entry from the Request Body as well as the full contents of the request body under “The Full Body”.

PSCustomObject Output
PSCustomObject Output

Also, notice the results from get-member shows the JSON Message Request was converted to a PSCusotmObject.

That is the basics of Azure Automation webhooks. Runbooks are not limited to starting by a schedule, but can be triggered by webhooks to respond to events in your environment.  Event driven runbooks provide flexibility and reliability for automation tasks.

One thought on “Webhooks and Azure Automation Runbooks

  1. Thank you for posting such helpful information regarding webhooks & automatic runbooks. It will be helpful for beginners like me to learn such skills.
    I will be looking forward to new updates.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.