Compartilhar via


definição de resources.webhooks.webhook

Um recurso de webhook permite que você integre seu pipeline a um serviço externo para automatizar o fluxo de trabalho.

webhooks:
- webhook: string # Required as first property. Name of the webhook.
  connection: string # Required. Name of the connection. In case of offline webhook this will be the type of Incoming Webhook otherwise it will be the type of the webhook extension.
  type: string # Name of the webhook extension. Leave this empty if it is an offline webhook.
  filters: [ filter ] # List of trigger filters.

Definições que fazem referência a essa definição: resources.webhooks

Propriedades

webhook String. Obrigatório como primeira propriedade.
Nome do webhook. Valores aceitáveis: [-_A-Za-z0-9]*.

connection String. Obrigatórios.
Nome da conexão. No caso de webhook offline, esse será o tipo de Webhook de entrada, caso contrário, ele será o tipo da extensão de webhook.

type String.
Nome da extensão de webhook. Deixe isso vazio se for um webhook offline.

filtersresources.webhooks.webhook.filters.
Lista de filtros de gatilho.

Exemplos

Exemplo básico

Você pode definir seu pipeline da seguinte maneira.

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

Para disparar o pipeline usando o webhook, você precisa fazer uma solicitação POST para https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview. Esse ponto de extremidade está disponível publicamente e nenhuma autorização é necessária. A solicitação deve ter o corpo a seguir.

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Ao acessar dados do corpo da solicitação do webhook, isso pode levar a um YAML incorreto. Por exemplo, se no pipeline anterior, sua etapa lê - script: echo ${{ parameters.WebHook.resource.message }}, e você aciona o pipeline por meio de um webhook, o pipeline não será executado. Isso ocorre porque, no processo de substituição de ${{ parameters.WebHook.resource.message.title }} por message, que contém o seguinte JSON, o YAML gerado se torna inválido.

{
  "title": "Hello, world!",
  "subtitle": "I'm using WebHooks!"
}

Como o YAML gerado se torna inválido, nenhuma execução de pipeline é enfileirada em resposta.

Impedir execuções de pipeline não autorizadas

Os webhooks permitem que qualquer pessoa dispare seu pipeline, desde que saibam os nomes da sua organização e da conexão de serviço de webhook.

Você pode impedir execuções de pipeline não autorizadas definindo um segredo ao criar uma conexão de serviço webhook de entrada. Você também precisa especificar o nome do cabeçalho HTTP que contém a soma de verificação SHA-1 do corpo do webhook.

Para verificar se uma chamada à API REST do webhook de entrada está autorizada, o Azure Pipelines calcula a soma de verificação SHA-1 do corpo da solicitação usando o segredo como chave. Em seguida, ele o compara à soma de verificação passada no cabeçalho da solicitação. Dessa forma, o chamador prova que sabe o segredo.

Vamos examinar um exemplo. Digamos que você configurou uma conexão de serviço webhook de entrada chamada IncomingWH, especificou que o segredo é secrete que a soma de verificação é enviada no cabeçalho HTTP chamado X-WH-Checksum. Imagine que você tem um pipeline que define um recurso do Webhook.

Digamos que você queira disparar o pipeline usando o seguinte corpo da solicitação:

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

Para fazer isso, você precisa fazer uma solicitação POST e https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/IncomingWH?api-version=6.0-preview adicionar o X-WH-Checksum cabeçalho com o valor de 750D33212D3AD4932CC390819050734831A0A94F. Você não precisa especificar nenhum nome de usuário & senha ou qualquer outro tipo de informação de autenticação.

O Azure Pipelines calculará independentemente a soma de verificação SHA-1 do corpo usando secret como chave e gerará o mesmo 750D33212D3AD4932CC390819050734831A0A94F valor. Como os valores correspondem, a chamada é autorizada e a fila de pipeline continua.

Você calcula o valor do X-WH-Checksum cabeçalho, em pseudocódigo, como SHA1(secret).ComputeHash(requestBody). Você pode usar . Classe do System.Security.Cryptography.HMACSHA1 NET para essa finalidade.

Para evitar falhas de validação devido a novas linhas ou espaços em branco, recomendamos que você envie o corpo de forma minimizada. Ou seja, enviar

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

em vez de

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Embora os dois objetos JSON acima representem o mesmo objeto, eles geram diferentes somas de verificação SHA-1. Isso ocorre porque o SHA-1 é calculado em sua representação de cadeia de caracteres, o que é diferente.

Confira também