Iniciar um runbook a partir de um webhook

Um webhook permite que um serviço externo inicie um determinado runbook no Automatização do Azure através de uma única requisição HTTP. Os serviços externos incluem Azure DevOps Services, GitHub, Azure Monitor logs e aplicações personalizadas. Um serviço desse tipo pode iniciar um runbook utilizando um webhook, sem a necessidade de implementar a API completa do Automatização do Azure. Pode comparar webhooks com outros métodos de iniciar um runbook em Iniciar um runbook em Automatização do Azure.

WebhooksVisão geral

Para compreender os requisitos do cliente para TLS 1.2 ou superior com webhooks, veja TLS para Automatização do Azure.

Propriedades do Webhook

A tabela seguinte descreve as propriedades que você deve configurar para um webhook.

Propriedade	Descrição
Nome	Nome do webhook. Você pode fornecer o nome que quiser, desde que não seja exposto ao cliente. É apenas utilizado para você identificar o runbook no Automatização do Azure. Como boa prática, deve dar ao webhook um nome associado ao cliente que o utiliza.
URL	URL do webhook. Este é o endereço exclusivo que um cliente chama com um HTTP POST para iniciar o runbook associado ao webhook. É gerado automaticamente quando você cria o webhook. Não pode especificar um URL personalizado. O URL contém um token de segurança que permite que um sistema de terceiros invoque o runbook sem autenticação adicional. Por este motivo, deve tratar o URL como uma palavra-passe. Por razões de segurança, só pode ver a URL no portal do Azure ao criar o webhook. Observe o URL em um local seguro para uso futuro.
Data de validade	Data de expiração do webhook, após a qual já não poderá ser utilizado. Pode modificar a data de expiração após a criação do webhook, desde que o webhook não tenha expirado.
Ativado	Configuração que indica se o webhook está habilitado por padrão quando é criado. Se você definir essa propriedade como Disabled, nenhum cliente poderá usar o webhook. Você pode definir essa propriedade ao criar o webhook ou em qualquer outro momento após sua criação.

Parâmetros usados quando o webhook inicia um runbook

Um webhook pode definir valores para parâmetros de runbook que são usados quando o runbook é iniciado. O webhook deve incluir valores para quaisquer parâmetros de runbook obrigatórios e pode incluir valores para parâmetros opcionais. Um valor de parâmetro configurado para um webhook pode ser modificado mesmo após a criação do webhook. Vários webhooks vinculados a um único runbook podem usar valores de parâmetros de runbook diferentes. Quando um cliente inicia um runbook usando um webhook, o cliente não pode alterar os valores de parâmetro definidos no webhook.

Para receber dados do cliente, o runbook suporta um único parâmetro chamado WebhookData. Este parâmetro define um objeto que contém dados que o cliente inclui em uma solicitação POST.

Propriedades WebhookData

O WebhookData parâmetro tem as seguintes propriedades:

Propriedade	Descrição
WebhookName	Nome do webhook.
RequestHeader	PSCustomObject que contém os cabeçalhos da solicitação POST de entrada.
RequestBody	Corpo da requisição POST recebida. Esse corpo mantém qualquer formatação de dados, como string, JSON, XML ou codificada em formulário. O runbook deve ser escrito para trabalhar com o formato de dados esperado.

Não é necessária a configuração do webhook para suportar o parâmetro WebhookData, e não é necessário que o runbook o aceite. Se o runbook não definir o parâmetro, todos os detalhes da solicitação enviada pelo cliente serão ignorados.

Nota

Ao chamar um webhook, o cliente deve sempre armazenar quaisquer valores de parâmetro caso a chamada falhe. Se houver uma interrupção de rede ou problema de conexão, o aplicativo não poderá recuperar chamadas de webhook com falha.

Se especificares um valor para WebhookData na criação do webhook, ele será substituído quando o webhook iniciar o runbook com os dados da solicitação POST do cliente. Isso acontece mesmo que o aplicativo não inclua nenhum dado no corpo da solicitação.

Se você iniciar um runbook que define WebhookData usando um mecanismo diferente de um webhook, você pode fornecer um valor para WebhookData que o runbook reconheça. Esse valor deve ser um objeto com as mesmas propriedades do WebhookData parâmetro para que o runbook possa trabalhar com ele da mesma forma que funciona com objetos reais WebhookData passados por um webhook.

Por exemplo, se estiveres a iniciar o runbook seguinte a partir do portal do Azure e quiseres passar alguns dados de webhook de exemplo para testes, tens de passar os dados em JSON na interface do utilizador.

Parâmetro WebhookData da interface do usuário

Para o próximo exemplo de runbook, vamos definir as seguintes propriedades para WebhookData:

WebhookName: MyWebhook
RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

Agora passamos o seguinte objeto JSON na interface do usuário para o WebhookData parâmetro. Este exemplo, com retornos de carro e caracteres de nova linha, corresponde ao formato que é passado de um webhook.

{"WebhookName":"mywebhook","RequestBody":"[\r\n {\r\n \"ResourceGroup\": \"vm01\",\r\n \"Name\": \"vm01\"\r\n },\r\n {\r\n \"ResourceGroup\": \"vm02\",\r\n \"Name\": \"vm02\"\r\n }\r\n]"}

Iniciar o parâmetro WebhookData da interface do usuário

Nota

O Automatização do Azure regista os valores de todos os parâmetros de entrada no âmbito do trabalho do runbook. Assim, qualquer entrada fornecida pelo cliente na solicitação webhook é registrada e disponível para qualquer pessoa com acesso ao trabalho de automação. Por esse motivo, você deve ser cauteloso ao incluir informações confidenciais em chamadas webhook.

Segurança do webhook

A segurança de um webhook depende da privacidade do URL, que contém um token de segurança que permite invocar o webhook. O Automatização do Azure não realiza autenticação num pedido desde que seja feito para a URL correta. Por este motivo, os clientes não devem utilizar webhooks para runbooks que realizam operações altamente confidenciais sem usar um meio alternativo de validar a requisição.

Considere as seguintes estratégias:

Você pode incluir lógica num runbook para determinar se ele é chamado pelo webhook. Faça com que o runbook verifique a propriedade do parâmetro WebhookNameWebhookData. O runbook pode executar uma validação adicional procurando por determinadas informações na propriedade RequestHeader e na propriedade RequestBody.
Faça com que o runbook execute alguma validação de uma condição externa quando receber uma solicitação de webhook. Por exemplo, considere um runbook que é chamado pelo GitHub sempre que há um novo commit num repositório do GitHub. O runbook pode ligar-se ao GitHub para validar que ocorreu um novo commit antes de continuar.
Automatização do Azure suporta as tags de serviço de rede virtual Azure, especificamente GuestAndHybridManagement. Pode usar etiquetas de serviço para definir controlos de acesso à rede em grupos de segurança rede ou Azure Firewall e ativar webhooks dentro da sua rede virtual. É possível utilizar etiquetas de serviço em vez de endereços IP específicos quando criar regras de segurança. Ao especificar o nome da etiqueta de serviço GuestAndHybridManagement no campo de origem ou destino adequado de uma regra, pode permitir ou negar o tráfego para o serviço de Automatização. Esta etiqueta de serviço não suporta permitir um controlo mais granular ao restringir os intervalos de IP a uma região específica.

Criar um webhook

Nota

Quando você usa o webhook com o runbook do PowerShell 7, ele converte automaticamente o parâmetro de entrada do webhook em um JSON inválido. Para obter mais informações, consulte Problemas conhecidos - PowerShell 7.1 (visualização). Recomendamos que você use o webhook com o runbook do PowerShell 5.
Usar um webhook para iniciar um runbook em Python não é suportado.

Para criar um webhook, siga estes passos:

Crie o runbook do PowerShell com o seguinte código:

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

write-output "start"
write-output ("object type: {0}" -f $WebhookData.gettype())
write-output $WebhookData
write-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

Crie um webhook usando o portal Azure, ou PowerShell ou API REST. Um webhook requer um runbook publicado. Este guia utiliza uma versão modificada do runbook criada a partir de Criar um runbook de Automatização do Azure.
Para criar um webhook usando o portal Azure, faça o seguinte:
1. Inicie sessão no portal Azure.
2. No portal Azure, navegue até à sua conta de Automação.
3. Em Automação de Processos, selecione Runbooks para abrir a página Runbooks .
4. Selecione seu runbook na lista para abrir a página Visão geral do runbook.
5. Selecione Adicionar webhook para abrir a página Adicionar Webhook .
6. Na página Adicionar Webhook, selecione Criar novo webhook.
7. Introduza o Nome do webhook. A data de expiração do campo Expira é definida, por padrão, para um ano a partir da data atual.
8. Selecione o ícone de cópia ou pressione Ctrl + C copie o URL do webhook. Em seguida, salve o URL em um local seguro.
  
  Importante
  
  Depois de criar o webhook, não é possível recuperar o URL novamente. Certifique-se de copiá-lo e registá-lo conforme anteriormente mencionado.
9. Selecione OK para retornar à página Adicionar Webhook .
10. Na página Adicionar Webhook, selecione Configurar parâmetros e executar configurações para abrir a página Parâmetros.
11. Revise página Parâmetros. Para o runbook de exemplo usado neste artigo, nenhuma alteração é necessária. Selecione OK para retornar à página Adicionar Webhook .
12. Na página Adicionar Webhook, selecione Criar. O webhook é criado e você retorna à página Visão geral do Runbook.
Para criar um webhook usando o PowerShell, faça o seguinte:
1. Verifique se você tem a versão mais recente do módulo Az do PowerShell instalada.
2. Inicie sessão em Azure interativamente usando o cmdlet Connect-AzAccount e siga as instruções.
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
3. Utilize o cmdlet New-AzAutomationWebhook para criar um webhook para um runbook de automação. Forneça um valor apropriado para as variáveis e, em seguida, execute o script.
```
# Initialize variables with your relevant values
$resourceGroup = "resourceGroupName"
$automationAccount = "automationAccountName"
$runbook = "runbookName"
$psWebhook = "webhookName"

# Create webhook
$newWebhook = New-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook `
    -RunbookName $runbook `
    -IsEnabled $True `
    -ExpiryTime "12/31/2022" `
    -Force

# Store URL in variable; reveal variable
$uri = $newWebhook.WebhookURI
$uri
```
  A saída será um URL semelhante a: https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
4. Você também pode verificar o webhook, com o cmdlet do PowerShell Get-AzAutomationWebhook.
```
Get-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
Para criar um webhook usando a API REST, faça o seguinte:

O comando PUT está documentado em Webhook - Create Or Update. Este exemplo usa o cmdlet do PowerShell Invoke-RestMethod para enviar a solicitação PUT.
1. Crie um arquivo chamado webhook.json e, em seguida, cole o seguinte código:
```
{
"name": "RestWebhook",
"properties": {
    "isEnabled": true,
    "expiryTime": "2022-03-29T22:18:13.7002872Z",
    "runbook": {
    "name": "runbookName"
    }
}
}
```
  Antes de executar, modifique o valor da propriedade runbook:name com o nome real do seu runbook. Consulte as propriedades do Webhook para obter mais informações sobre essas propriedades.
2. Verifique se você tem a versão mais recente do módulo Az do PowerShell instalada.
3. Inicie sessão em Azure interativamente usando o cmdlet Connect-AzAccount e siga as instruções.
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
4. Forneça um valor apropriado para as variáveis e, em seguida, execute o script.
```
# Initialize variables
$subscription = "subscriptionID"
$resourceGroup = "resourceGroup"
$automationAccount = "automationAccount"
$runbook = "runbookName"
$restWebhook = "webhookName"
$file = "path\webhook.json"

# consume file
$body = Get-Content $file

# Craft Uri
$restURI = "https://management.azure.com/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Automation/automationAccounts/$automationAccount/webhooks/$restWebhook`?api-version=2015-10-31"
```
5. Execute o script a seguir para obter um token de acesso. Se o token de acesso expirou, você precisará executar o script novamente.
```
# Obtain access token
$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}
```
6. Execute o script a seguir para criar o webhook usando a API REST.
```
# Invoke the REST API
# Store URL in variable; reveal variable
$response = Invoke-RestMethod -Uri $restURI -Method Put -Headers $authHeader -Body $body
$webhookURI = $response.properties.uri
$webhookURI
```
  A saída é um URL semelhante a: https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
7. Você também pode usar Webhook - Get para obter o webhook identificado pelo seu nome. Você pode executar os seguintes comandos do PowerShell:
```
$response = Invoke-RestMethod -Uri $restURI -Method GET -Headers $authHeader
$response | ConvertTo-Json
```

Use um webhook

Este exemplo usa o cmdlet do PowerShell Invoke-WebRequest para enviar a solicitação POST para seu novo webhook.

Para usar um webhook, siga estas etapas:

Prepare os valores a passar para o runbook como corpo da solicitação webhook. Para valores relativamente simples, você pode criar scripts para os valores da seguinte maneira:
```
$Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names
```
Para conjuntos maiores, você pode querer usar um arquivo. Crie um arquivo chamado names.json e, em seguida, cole o seguinte código:
```
[
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]
```
Altere o valor da variável $file com o caminho real para o arquivo json antes de executar os seguintes comandos do PowerShell.
```
# Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file 
```

Execute os seguintes comandos do PowerShell para chamar o webhook usando a API REST.

$response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

Para fins ilustrativos, foram feitas duas chamadas para os dois métodos diferentes de produção do corpo. Para a produção, use apenas um método. A saída deve ser semelhante da seguinte forma (apenas uma saída é mostrada):

Saída da chamada webhook.

O cliente recebe um dos seguintes códigos de retorno do POST pedido.

Código	Texto	Descrição
202	Aceite	A solicitação foi aceita e o runbook foi colocado na fila com sucesso.
400	Pedido Incorreto	O pedido não foi aceite por uma das seguintes razões: O webhook expirou. O webhook está desativado. O token no URL é inválido.
404	Não Encontrado	O pedido não foi aceite por uma das seguintes razões: O webhook não foi encontrado. O runbook não foi encontrado. A conta não foi encontrada.
500	Erro de Servidor Interno	O URL era válido, mas ocorreu um erro. Reenvie a solicitação.

Supondo que a solicitação seja bem-sucedida, a resposta do webhook contém o ID do trabalho no formato JSON, conforme mostrado abaixo. Ele contém um único ID de trabalho, mas o formato JSON permite possíveis aprimoramentos futuros.

{"JobIds":["<JobId>"]}

O cmdlet Get-AzAutomationJobOutput do PowerShell será usado para obter a saída. A API Automatização do Azure também podia ser utilizada.
```
#isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output
```
Quando você aciona um runbook criado na etapa anterior, ele criará um trabalho e a saída deverá ser semelhante à seguinte:

Atualizar um webhook

Quando um webhook é criado, tem um período de validade de 10 anos, após o qual expira automaticamente. Depois de um webhook expirar, não é possível reativá-lo. Você só pode removê-lo e, em seguida, recriá-lo. Pode expandir um webhook que ainda não atingiu o tempo de expiração. Para estender um webhook, execute as seguintes etapas:

Navegue para o runbook que contém o webhook.
Em Recursos, selecione Webhooks e, em seguida, o webhook que você deseja estender.
Na página Webhook, escolha uma nova data e hora de expiração e selecione Salvar.

Analise a chamada de API Webhook - Update e o cmdlet do PowerShell Set-AzAutomationWebhook para outras possíveis modificações.

Limpar recursos

Aqui estão exemplos de como remover um webhook de um Runbook de Automação.

Usando o PowerShell, o cmdlet Remove-AzAutomationWebhook pode ser usado conforme mostrado abaixo. Nenhuma saída é retornada.

Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

Usando REST, o REST Webhook - Delete API pode ser usado como mostrado abaixo.
```
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader
```
Um resultado de StatusCode : 200 significa uma eliminação bem-sucedida.

Criar runbook e webhook com modelo ARM

Webhooks de automação também podem ser criados usando modelos Azure Resource Manager. Este modelo de exemplo cria uma conta de automação, quatro runbooks e um webhook para o runbook especificado.

Para criar um webhook usando um modelo ARM, siga estas etapas:

Crie um arquivo chamado webhook_deploy.json e, em seguida, cole o seguinte código:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "automationAccountName": {
            "type": "String",
            "metadata": {
                "description": "Automation account name"
            }
        },
        "webhookName": {
            "type": "String",
            "metadata": {
                "description": "Webhook Name"
            }
        },
        "runbookName": {
            "type": "String",
            "metadata": {
                "description": "Runbook Name for which webhook will be created"
            }
        },
        "WebhookExpiryTime": {
            "type": "String",
            "metadata": {
                "description": "Webhook Expiry time"
            }
        },
        "_artifactsLocation": {
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.automation/101-automation/",
            "type": "String",
            "metadata": {
                "description": "URI to artifacts location"
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Automation/automationAccounts",
            "apiVersion": "2020-01-13-preview",
            "name": "[parameters('automationAccountName')]",
            "location": "[resourceGroup().location]",
            "properties": {
                "sku": {
                    "name": "Free"
                }
            },
            "resources": [
                {
                    "type": "runbooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('runbookName')]",
                    "location": "[resourceGroup().location]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]"
                    ],
                    "properties": {
                        "runbookType": "Python2",
                        "logProgress": "false",
                        "logVerbose": "false",
                        "description": "Sample Runbook",
                        "publishContentLink": {
                            "uri": "[uri(parameters('_artifactsLocation'), 'scripts/AzureAutomationTutorialPython2.py')]",
                            "version": "1.0.0.0"
                        }
                    }
                },
                {
                    "type": "webhooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('webhookName')]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]",
                        "[parameters('runbookName')]"
                    ],
                    "properties": {
                        "isEnabled": true,
                        "expiryTime": "[parameters('WebhookExpiryTime')]",
                        "runbook": {
                            "name": "[parameters('runbookName')]"
                        }
                    }
                }
            ]
        }
    ],
    "outputs": {
        "webhookUri": {
            "type": "String",
            "value": "[reference(parameters('webhookName')).uri]"
        }
    }
}

O seguinte exemplo de código do PowerShell implanta o modelo a partir da sua máquina. Forneça um valor apropriado para as variáveis e, em seguida, execute o script.

$resourceGroup = "resourceGroup"
$templateFile = "path\webhook_deploy.json"
$armAutomationAccount = "automationAccount"
$armRunbook = "ARMrunbookName"
$armWebhook = "webhookName"
$webhookExpiryTime = "12-31-2022"

New-AzResourceGroupDeployment `
    -Name "testDeployment" `
    -ResourceGroupName $resourceGroup `
    -TemplateFile $templateFile `
    -automationAccountName $armAutomationAccount `
    -runbookName $armRunbook `
    -webhookName $armWebhook `
    -WebhookExpiryTime $webhookExpiryTime

Nota

Por motivos de segurança, o URI só é retornado na primeira vez que um modelo é implantado.

Próximos passos

Para ativar um runbook a partir de um alerta, consulte Utilize um alerta para ativar um runbook do Automatização do Azure.
Para resolver problemas relacionados com o início de runbooks do Automatização do Azure usando webhooks, veja Resolução de problemas de runbook.

Comentários

Esta página foi útil?

Last updated on 2026-04-20

Iniciar um runbook a partir de um webhook

Propriedades do Webhook

Parâmetros usados quando o webhook inicia um runbook

Segurança do webhook

Criar um webhook

Use um webhook

Atualizar um webhook

Limpar recursos

Criar runbook e webhook com modelo ARM

Próximos passos

Comentários

Recursos adicionais