Use um webhook como gatilho para os Aplicativos Lógicos do Azure e o Power Automate

Webhooks são simples retornos de chamada de HTTP usados para fornecer notificações de eventos. Os Aplicativos Lógicos do Azure e o Power Automate permitem que você use webhooks como gatilhos. Um aplicativo lógico ou fluxo aguarda esse gatilho e executa uma ação sempre que o gatilho é acionado. Este tutorial demonstra como usar um webhook como gatilho.

Observação

Usaremos o GitHub como exemplo de um serviço que pode enviar notificações via webhooks. No entanto, as técnicas demonstradas aqui podem ser estendidas para qualquer serviço que utilizar webhooks.

Pré-requisitos

• Uma das assinaturas a seguir:
  • Azure, se você estiver usando Aplicativos Lógicos do Azure.
  • Power Automate
• Experiência básica para a criação de aplicativos lógicos ou fluxos e conectores personalizados.
• Caso esteja usando Aplicativos Lógicos, primeiro crie um conector personalizado dos Aplicativos Lógicos do Azure.
• Noções básicas sobre webhooks.
• Compreensão básica da Especificação OpenAPI (anteriormente conhecido como Swagger).
• Uma conta do GitHub.
• A definição OpenAPI de exemplo para este tutorial.

A definição OpenAPI

Os webhooks são implementados nos Aplicativos Lógicos e no Power Automate como parte de um conector personalizado e, portanto, você precisa fornecer uma definição OpenAPI que defina a forma do webhook. Se você deseja criar um gatilho, mas não tem uma definição OpenAPI, você pode usar a IU dos gatilhos no assistente de conector personalizado para definir gatilhos de webhook.

A definição OpenAPI contém três partes que são essenciais para fazer o webhook funcionar:

• Criar o webhook
• Definir a solicitação de entrada do webhook a partir da API (nesse caso, o GitHub)
• Excluir o webhook

Criar o webhook

O webhook é criado no lado do GitHub por um HTTP POST para /repos/{owner}/{repo}/hooks. Quando um novo aplicativo lógico ou fluxo é criado, ele publica nessa URL usando o gatilho definido na definição OpenAPI. Também publica na URL se o gatilho for modificado. No exemplo a seguir, a propriedade post contém o esquema da solicitação que será postado no GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

Importante

A propriedade "x-ms-trigger": "single" é uma extensão de esquema que informa aos Aplicativos Lógicos e ao Power Automate para exibir esse webhook na lista de gatilhos disponíveis no designer e, portanto, não deixe de incluí-lo.

Definir a solicitação de entrada do webhook a partir da API

A forma da solicitação de gancho de entrada (a notificação do GitHub para os Aplicativos Lógicos ou o Power Automate) é definida na propriedade x-ms-notification-content personalizada, conforme mostrado no exemplo anterior. Ela não precisa conter todo o conteúdo da solicitação, apenas as partes que você deseja usar em seu aplicativo lógico ou fluxo.

Excluir o webhook

A definição OpenAPI deve incluir uma definição de como excluir o webhook. Os Aplicativos Lógicos e o Power Automate tentam excluir o webhook se você atualizar o gatilho e excluir o aplicativo lógico ou fluxo.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

Nenhum cabeçalho adicional é incluído para a exclusão da chamada de webhook. A mesma conexão usada no conector também é usada para excluir a chamada de webhook.

Importante

Para que os Aplicativos Lógicos ou o Power Automate excluam um webhook, a API precisa incluir um cabeçalho HTTP Location na resposta 201 no momento em que o webhook é criado. O cabeçalho Location deve conter o caminho para o webhook que será usado com o HTTP DELETE. Por exemplo, o Location incluído com a resposta do GitHub segue este formato: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Habilitar autenticação no GitHub

A API que envia a solicitação de webhook para os Aplicativos Lógicos ou para o Power Automate geralmente usa alguma forma de autenticação, e o GitHub não é uma exceção. O GitHub oferece suporte a vários tipos de autenticação. Usaremos os tokens de acesso pessoal do GitHub para este tutorial.

1. Navegue até GitHub e entre, se ainda não o tiver feito.

2. No canto superior direito, selecione sua imagem do perfil e, em seguida, no menu, escolha Configurações.

   

3. No menu à esquerda, selecione Configurações do desenvolvedor e depois Tokens de acesso pessoal.

4. Escolha o botão Gerar novo token e confirme sua senha, se solicitado.

   

5. Na caixa Descrição do token, digite uma descrição.

6. Marque a caixa de seleção admin:repo_hook.

   

7. Selecione o botão Gerar token.

8. Anote o novo token.

   

   Importante

   Você não conseguirá acessar esse token novamente. Você deve copiá-lo e colá-lo em algum lugar para usar posteriormente no tutorial.

Importar a definição OpenAPI

Comece importando a definição OpenAPI para Aplicativos Lógicos ou para o Power Automate.

Importar a definição OpenAPI para Aplicativos Lógicos

1. Acesse o portal do Azure e abra o conector dos Aplicativos Lógicos que você criou anteriormente em Criar um conector personalizado dos Aplicativos Lógicos do Azure.

2. No menu do conector, escolha Conector de Aplicativos Lógicos e escolha Editar.

   

3. Em Geral, escolha Carregar um arquivo OpenAPI e navegue até o arquivo OpenAPI que você baixou.

   

Importar a definição OpenAPI para o Power Automate

1. Acesse flow.microsoft.com.

2. No canto superior direito, escolha o ícone de engrenagem e escolha Conectores personalizados.

   

3. Escolha Criar conector personalizado e escolha Importar uma coleção de Postman.

   

4. Insira um nome para o conector personalizado, navegue até o arquivo OpenAPI que você baixou e escolha Conectar.

   

   Parâmetro	Valor
   Título do conector personalizado	"GitHubDemo"

Concluir a criação do conector personalizado

1. Na página Geral, escolha Continuar.

2. Na página Segurança, em Tipo de autenticação, selecione Autenticação básica.

3. Na seção Autenticação básica, nos campos de rótulo, insira o texto Nome de usuário e Senha. Esses são apenas os rótulos que serão exibidos quando o gatilho for usado em um aplicativo lógico ou fluxo.

   

4. Na parte superior do assistente, verifique se o nome está definido como "GitHubDemo" e selecione Criar conector.

Agora você está pronto para usar o gatilho em um aplicativo lógico ou fluxo ou pode continuar a ler sobre como criar gatilhos usando a interface do usuário.

Criar gatilhos de webhook a partir da IU

Nesta seção, mostraremos como criar um gatilho na interface do usuário sem ter nenhuma definição de gatilho em sua definição da OpenAPI. Comece com uma definição OpenAPI de linha de base ou comece do zero no assistente de conector personalizado.

1. Na página Geral, certifique-se de especificar uma descrição e URL.

   Parâmetro	Valor
   Descrição	"GitHub é um repositório de código-fonte social."
   URL	"api.github.com"

2. Na página Segurança, configure a autenticação básica como você fez na seção anterior.

3. Na página Definição, escolha + Novo gatilho e preencha a descrição do seu gatilho. Neste exemplo, você está criando um gatilho que é acionado quando uma solicitação por pull é feita em um repositório.

   

   Parâmetro	Valor
   Resumo	"Dispara quando uma solicitação pull é feita para um repositório selecionado"
   Descrição	"Dispara quando uma solicitação pull é feita para um repositório selecionado"
   ID da Operação	"webhook-PR-trigger"
   Visibilidade	"nenhum" (veja abaixo para obter mais informações)
   Tipo de gatilho	"Webhook"

   A propriedade Visibilidade para operações e parâmetros em um aplicativo lógico ou fluxo possui as seguintes opções:

   • nenhum: normalmente exibido no aplicativo lógico ou no fluxo
   • avançado: oculto em um menu adicional
   • interno: ocultado do usuário
   • importante: sempre exibido para o usuário primeiro

4. A área Solicitação exibe informações com base na solicitação HTTP para a ação. Escolha Importar da amostra.

   

5. Defina a solicitação para o gatilho de webhook e escolha Importar. Fornecemos uma amostra para você importar (abaixo da imagem). Para obter mais informações, consulte a referência da API do GitHub. Os Aplicativos Lógicos e o Power Automate adicionam automaticamente cabeçalhos de segurança e content-type padrão e, portanto, você não precisa defini-los durante a importação de um exemplo.

   

   Parâmetro	Valor
   Verbo	"POSTAGEM"
   URL	"https://api.github.com/repos/{owner}/{repo}/hooks"
   Corpo	Consulte abaixo

   {
     "name": "web",
     "active": true,
     "events": [
       "pull_request"
     ],
     "config": {
       "url": "http://example.com/webhook"
     }
   }
   

6. A área Resposta exibe informações com base na resposta HTTP para a ação. Escolha Adicionar resposta padrão.

   

7. Defina a resposta para o gatilho de webhook e escolha Importar. Mais uma vez, fornecemos uma amostra para você importar. Para obter mais informações, consulte a referência da API do GitHub.

   

   {
     "action": "opened",
     "number": 1,
     "pull_request": {
       "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
       "state": "open",
       "locked": false,
       "title": "Update the README with new information",
       "user": {
         "login": "baxterthehacker",
         "type": "User"
       }
     }
   }
   

8. Na área Configuração do gatilho, selecione o parâmetro que deve receber o valor da URL de retorno de chamada do GitHub. Trata-se da propriedade url no objeto config.

   

9. Na parte superior do assistente, digite um nome e escolha Criar conector.

Usar o webhook como um gatilho

Agora que você tem tudo configurado, é possível usar o webhook em um aplicativo lógico ou em um fluxo. A seguir, criaremos um fluxo que enviará uma notificação por push para o aplicativo móvel do Power Automate sempre que nosso repositório do GitHub receber um git push.

1. Em flow.microsoft.com, na parte superior da página, escolha Meus fluxos.

2. Escolha Criar em branco e, na próxima página, escolha Pesquisar centenas de conectores e gatilhos.

   

3. No designer do Power Automate, pesquise o conector personalizado que você registrou anteriormente.

   

   Escolha o item na lista para usá-lo como um gatilho.

4. Por ser a primeira vez que você usou esse conector personalizado, é necessário conectá-lo. Digite as informações de conexão e escolha Criar.

   

   Parâmetro	Valor
   Nome da conexão	Um nome descritivo
   Nome do Usuário	Seu nome de usuário do GitHub
   Senha	O token de acesso pessoal que você criou anteriormente

5. Insira os detalhes sobre o repositório que deseja monitorar. Você pode reconhecer os campos do objeto WebhookRequestBody no arquivo OpenAPI.

   

   Parâmetro	Valor
   proprietário	O proprietário do repositório a ser monitorado
   repositório	O repositório a ser monitorado

   Importante

   Você deve usar um repositório para o qual sua conta tenha direitos. A maneira mais fácil de fazer isso seria usar seu próprio repositório.

6. Escolha + Nova etapa e selecione Adicionar uma ação.

7. Procure e selecione a ação Notificação por push.

   

8. Digite algum texto no campo Texto e nos outros campos, usando valores da caixa de diálogo de conteúdo dinâmico. Observe que esses valores vêm do objeto WebhookPushResponse no arquivo OpenAPI.

   

   Parâmetro	Valor
   Nome da conexão	Um nome descritivo
   Nome do Usuário	Seu nome de usuário do GitHub
   Senha	O token de acesso pessoal que você criou anteriormente

9. Na parte superior da página, dê um nome ao fluxo e selecione Criar fluxo.

   

Verificação e solução de problemas

Para verificar se tudo está configurado corretamente, selecione Meus fluxos e, em seguida, escolha o ícone de informações ao lado do novo fluxo para exibir o histórico de execução:

• Você já deve ver, pelo menos, uma execução "Bem-sucedida" na criação do webhook. Isso indica que o webhook foi criado com sucesso no lado do GitHub.

• Se a execução falhar, analise os detalhes de execução para ver o motivo da falha. Se a falha tiver ocorrido devido a uma resposta "404 Não Encontrado", é provável que sua conta do GitHub não tenha as permissões corretas para criar um webhook no repositório usado.

Resumo

Se tudo estiver configurado corretamente, você agora receberá notificações por push no aplicativo móvel do Power Automate sempre que ocorrer um git push no repositório do GitHub selecionado. Usando o processo acima, você pode usar qualquer serviço compatível com webhooks como um gatilho nos fluxos.

Próximas etapas

• Criar um conector personalizado para uma API Web
• Autenticar sua API e conector com o Microsoft Entra ID

Enviar comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.