One of the recently added features, Webhooks, enables you to trigger/execute a runbook from other cloud services / scripts / etc.

 

The great advantages of webhooks is:

  • Easy to trigger runbooks
  • Does not require authentication
  • uses a standard HTTP Post
  • You can submit a header and body when posting to the webhook, containing input information

This blog article will describe how to use the inputs from the HTTP post.

1.   Create a new runbook and open it in the editor

2.   Add a parameter called $Webhookdata

param ([object]$WebHookData)

This parameter will receive any information from the HTTP post.

Basically it contains 3 parts:

  • WebhookName – contains the webhook name
  • RequestHeader – contains information fomr the headers, you can decide what to send. usually this would be information like, who, what and when the runbook was triggered
  • RequestBody – contains information from the request body, this is also available for custom data. usually this part is used for the actual inputs to the runbook and it is recommended to send data as JSON strings for easy handling in the code.

More info about JSON in general

3.   Read each of the parts into separate variables:

$WebhookName    =   $WebhookData.WebhookName
$WebhookHeaders =   $WebhookData.RequestHeader
$WebhookBody    =   $WebhookData.RequestBody

4. Convert the JSON string in the body to an object using ConvertFrom-JSON

$Inputs = ConvertFrom-JSON $webhookdata.RequestBody

5. Access each of the submitted values

$ItemID = $Inputs.ID
$RootShare = $Inputs.RootShare
$ShareName = $Inputs.ShareName
$IsSecure = $Inputs.SecureShare
$Location = $Inputs.Location
$ShareOwner = $Inputs.ShareOwner.Split(";").Replace("i:0#.f|membership|","")
$ShareMembers = $Inputs.ShareMembers.Split(";").Replace("i:0#.f|membership|","")

6.   Publish the runbook

7. Add a webhook to the runbook. See the official documentation here

You’re done! Here is the complete workflow:

workflow New-DFSShareRequest
{
		param ([object]$WebHookData)
	
	$WebhookName    =   $WebhookData.WebhookName
    $WebhookHeaders =   $WebhookData.RequestHeader
    $WebhookBody    =   $WebhookData.RequestBody
	
	$Inputs = ConvertFrom-JSON $webhookdata.RequestBody
	
	$ItemID = $Inputs.ID
	$RootShare = $Inputs.RootShare
	$ShareName = $Inputs.ShareName
	$IsSecure = $Inputs.SecureShare
	$Location = $Inputs.Location
	$ShareOwner = $Inputs.ShareOwner.Split(";").Replace("i:0#.f|membership|","")
	$ShareMembers = $Inputs.ShareMembers.Split(";").Replace("i:0#.f|membership|","")
	
	Write-output "Share Name: $ShareName"
}

Next post in this series will discuss how to trigger a runbook using a web hook.