Gatilho de webhook

5 minutos

Webhooks são implementações populares baseadas em HTTP de um padrão de notificação de assinante-editor mais genérico. Eles fornecem uma maneira de as notificações serem entregues a um serviço externo (assinante) sempre que determinados eventos ocorrem em um sistema (editor).

O Power Automate e os Aplicativos Lógicos do Azure permitem que os criadores usem webhooks como gatilhos. Nesse cenário, os gatilhos desempenharão a função de um assinante que está registrando e cancelando o registro de webhooks em nome de um criador. O registro ocorre quando uma etapa em um fluxo de nuvem ou fluxo de trabalho de Aplicativos Lógicos é criada ou atualizada. Quando a etapa é removida, a plataforma cancela o registro do webhook.

Como o Copilot pode ajudar você a configurar o conector, ele também pode ajudar aqui. Você pode começar com solicitações simples e, à medida que progredir, melhorar sua implementação:

"Como definir um gatilho HTTP para meu conector personalizado?"
"Quais parâmetros devo incluir no meu gatilho de conector personalizado?"
"Você pode verificar minha lógica de gatilho para possíveis melhorias?"

O Copilot pode sugerir o melhor jeito de definir os gatilhos com base na sua API e nos requisitos do fluxo.

A captura de tela a seguir mostra um exemplo da interação entre assinante e editor.

As responsabilidades das partes estão descritas na tabela a seguir.

Editor (conector personalizado OpenAPI)	Assinante (Power Automate/Aplicativos Lógicos)
Fornece o ponto de extremidade de registro de assinatura.	Chama o ponto de extremidade de registro de assinatura quando um gatilho é criado ou atualizado em um fluxo.
Especifica o contrato de notificação, ou seja, qual objeto será passado com cada notificação. Deve incluir o cabeçalho HTTP de Localização na resposta 201 no momento em que um webhook é criado.	Fornece a URL do ponto de extremidade gerado automaticamente que aceitará as mensagens de notificação.
Mantém o registro de assinantes e seus pontos de extremidade de notificação.	Recebe e armazena informações de localização que serão usadas para cancelar o registro do webhook.
Emite uma solicitação POST para cada ponto de extremidade registrado e passa os dados relevantes no corpo da mensagem.	Recebe notificações, valida-as em relação ao esquema definido pelo conector personalizado e dispara a automação.
Cancela o registro/remove os pontos de extremidade em resposta à mensagem DELETE.	Emite uma mensagem DELETE para cancelar o registro do webhook quando a etapa do gatilho é excluída.

Os webhooks fornecem apenas o mecanismo de notificação e não dão suporte à manipulação dos dados. Frequentemente, uma implementação de webhook é complementada por uma ou mais ações que são projetadas para dar suporte aos dados ou à recuperação e à manipulação de objetos.

Requisitos de API

Para dar o suporte de webhook exigido por conectores personalizados, a implementação da API deve fornecer os seguintes parâmetros:

Um ponto de extremidade que aceita a mensagem de registro e retorna informações de localização
Uma definição do corpo da mensagem que é enviada com as mensagens de notificação
Um ponto de extremidade para aceitar a mensagem DELETE a fim de remover o registro do webhook

Normalmente, a implementação da API mantém uma lista interna de assinantes ativos, em que cada assinante é identificado por uma URL exclusiva. Para retornar essa URL ao assinante, a criação bem-sucedida do webhook é necessária para retornar uma resposta HTTP 201 e incluir um cabeçalho HTTP de Localização. O valor deste local será usado posteriormente pelo assinante para excluir o registro do webhook.

Criar um gatilho de webhook

Os conectores personalizados usam OpenAPI para descrever a implementação da API do editor, conforme exigido pelos webhooks. Para definir um gatilho de webhook em um conector personalizado, você precisa incluir três partes essenciais na definição OpenAPI:

Uma mensagem POST que descreve o registro do webhook
Definição de conteúdo para as respostas do webhook
Uma mensagem DELETE que descreve o processo de subdivisão do webhook

Mensagem de registro

A definição do gatilho deve incluir um método POST que é usado para registrar um webhook. Ele é definido de forma semelhante às ações.

A versão de especificação OpenAPI usada pelo Microsoft Power Platform não diferencia ações e gatilhos. A definição de conector personalizado usa a extensão personalizada x-ms-trigger para declarar um gatilho.

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

A presença da extensão x-ms-trigger indica que o método é um gatilho e não uma ação. Quando um gatilho é criado usando o assistente, essa extensão é adicionada automaticamente. No entanto, quando um conector personalizado é criado com base nas definições externas de OpenAPI, o processo de importação sempre cria ações. Nesse cenário, você precisa recriar os gatilhos usando o assistente e remover as definições de ação correspondentes.

Os valores possíveis para a extensão x-ms-trigger são single ou batch para diferenciar entre um objeto e as respostas da matriz. Um único objeto é incluído quando um webhook gera uma notificação para cada alteração. Essa abordagem é a mais comum com webhooks. Quando várias alterações são combinadas em uma única notificação, uma matriz de objetos é enviada. Essa abordagem é normalmente usada em gatilhos de sondagem e será discutida posteriormente no módulo.

Resposta do Webhook

As definições de conector personalizado podem descrever o conteúdo das respostas de webhook de entrada de seu serviço quando ocorre um evento. Embora não seja obrigatória, essa definição identifica os valores dinâmicos que estão disponíveis para o criador no momento do design na lista de conteúdo dinâmico.

Observação

Essa resposta não é da solicitação que cria e registra o webhook. Esses dados são enviados por seu serviço quando ocorre um evento.

A propriedade x-ms-notification-content personalizada é outra extensão usada no OpenAPI para definir o esquema de resposta do webhook.

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

Dica

Uma definição de resposta de webhook não precisa ter todo o conteúdo da resposta, apenas as partes que você deseja expor aos criadores de fluxo no momento do design na lista de conteúdo dinâmico.

Os dados enviados com a resposta do webhook não precisam conter, e podem não conter, todas as propriedades de que você precisa do objeto subjacente. Nessas situações, convém criar outras ações no conector personalizado para recuperação de informações. Por exemplo, uma loja da Web pode enviar apenas um novo identificador de pedido com a notificação "Quando um novo pedido é criado". Em seguida, o conector personalizado pode definir uma ação, como "Obter detalhes do pedido", que aceita um identificador de pedido e retorna informações expandidas sobre o pedido.

O contrário também é verdade. As respostas do webhook podem fornecer informações excessivas que não são exigidas ou necessárias em circunstâncias normais. Você só precisa descrever os dados que deseja mostrar no Power Automate ou na interface do criador de Aplicativos Lógicos. Se o criador precisar acessar mais dados que são enviados na notificação, ele poderá usar funções JSON para extrair diretamente essas propriedades da mensagem recebida.

Excluir mensagem

Para que o Power Automate ou os Aplicativos Lógicos excluam um webhook, a API deve incluir um cabeçalho HTTP de Localização na resposta no momento em que o webhook é criado.

Importante

Você deve definir o caminho da solicitação de exclusão do webhook como uma ação interna. Essa ação enviará uma solicitação DELETE para a URL especificada no cabeçalho do local.

Se essa ação não for definida ou se a API não incluir o cabeçalho do local, os webhooks serão criados, mas não excluídos, podendo causar problemas na implementação da API em tempo de execução.