Pular para o conteúdo principal

Webhooks

Visão Geral​

O DHuO foi concebido como uma plataforma extensível e integrável, de forma que sua utilização se encaixe em processos já existentes nas organizações.

As integrações podem ser feita de duas formas: por meio do DHuO CLI, onde as automações e sistemas externos enviam informações para o DHuO; e por meio de webhooks, onde os sistemas externos recebem informações do DHuO. Para saber mais sobre o DHuO CLI, acesse a seção DHuO CLI.

A funcionalidade de Webhook é uma forma de integrar o DHuO a outros sistemas de maneira automática e em tempo real. Por meio de webhooks, o DHuO notificará sistemas externos sempre que um evento acontecer na plataforma.

Com isso, é possível integrar com fluxos de APIOps ou DevOps existentes para, por exemplo, executar testes de qualidade quando um serviço de integração do DHuO for implantado em um ambiente de QA.

Atualmente o DHuO possui webhook para os seguintes eventos da plataforma:

  • Release de integrações
  • Deploy de integrações

O envio das notificações pode ser enviado para:

  • GitLab CI/CD
  • Azure Pipelines
  • Endpoints genéricos, capaz de receberem requisições POST

O DHuO conta também com um histórico de eventos notificados, com possibilidade de reprocessamento, caso necessário. Isso é útil em situações onde o sistema receptor do evento esteja indisponível ou incapaz de processar os eventos recebidos do DHuO.

Configuração​

Os webhooks são gerenciados no contexto da Organização. A partir da home, acesse o ícone de configurações da Organização ⚙ menu > Webhooks. Na página de webhooks, eles podem ser cadastrados, editados e excluídos. Cada tipo de evento e tipo de webhook possui configurações específicas.

No botão Histórico de um webhook é possível acessar o histórico de execuções (caso o webhook possua eventos enviados), conferir os detalhes de cada evento enviado e, caso necessário, fazer o reenvio do evento.

Durante o cadastro ou edição de um webhook também é possível testar o envio de eventos simulados. Isso é útil durante a configuração do webhook para não ser necessário realizar ações reais na plataforma para gerar eventos desnecessários nessa etapa de configuração.

Permissões​

Apenas usuários com papel de administrador da organização (Org Admin) podem gerenciar webhooks. Para saber mais, acesse a seção Papéis e permissões.

Parâmetros gerais​

Aqui estão os parâmetros gerais para a configuração de um webhook:

  • Nome: Obrigatório. Nome do webhook.
Informação adicional

Os webhooks são únicos por Organização. Não é possível ter mais de um webhook com o mesmo nome.

  • Evento: Obrigatório. Tipo do evento enviado pelo webhook. Opções: Integration Release, Integration Deploy.
  • Tipo: Obrigatório. Tipo do webhook a ser cadastrado. Determina o tipo do sistema que receberá o evento. Opções: Genérico, Azure Pipelines, GitLab CI/CD. Os dados enviados pelo DHuO são os mesmos, independente do tipo do webhook. O que diferencia é o formato de envio, conforme o tipo do webhook. Os detalhes estão descritos nas seções de parâmetros de cada tipo de webhook.
  • Status: Obrigatório. Determina se o webhook estará disponível para enviar eventos. Apenas webhooks ativos podem disparar eventos.

Parâmetros de evento: Integration Release​

  • Operação: Obrigatório. Ações onde o DHuO enviará eventos na manipulação de releases de uma integração. Opções: Todas (as ações), Create (criação), Delete (exclusão).
  • Status da operação: Obrigatório. Determina em quais momentos das operações de releases os eventos serão enviados. Opções: Todos (os momentos), Concluído (somente em caso de sucesso), Erro (somente em caso de falha).
  • Workspace: Obrigatório. Restringe a execução do webhook a workspaces específicos. Opções: Todos ou lista de workspaces específicos.
  • Integração: Obrigatório. Restringe a execução do webhook a integrações específicas. Opções: Todas ou lista de integrações específicas.

Parâmetros de evento: Integration Deploy​

  • Operação: Obrigatório. Ações onde o DHuO enviará eventos na realização de implantações de uma integração. Opções: Todas (as ações), Create (criação), Update (atualização), Delete (exclusão).
  • Status da operação: Obrigatório. Determina em quais momentos das operações de implantações os eventos serão enviados. Opções: Todos (os momentos), Concluído (somente em caso de sucesso), Erro (somente em caso de falha).
  • Workspace: Obrigatório. Restringe a execução do webhook a workspaces específicos. Opções: Todos ou lista de workspaces específicos.
  • Integração: Obrigatório. Restringe a execução do webhook a integrações específicas. Opções: Todas ou lista de integrações específicas.
  • Ambiente: Obrigatório. Restringe a execução do webhook as implantações de integrações em ambientes específicos. Opções: Todos ou lista de ambientes específicos.
  • Cluster: Obrigatório. Restringe a execução do webhook as implantações de integrações em clusters específicos. Opções: Todos ou lista de clusters específicos.

Parâmetros de tipo de webhook: Genérico​

Os webhooks do tipo Genérico recebem os dados do evento em formato JSON, por meio de uma requisição POST à URL cadastrada.

  • URL: Obrigatório. URL a receber os dados do evento do webhook.
  • Cabeçalhos: Lista de headers opcionais que serão adicionados na requisição para o endereço de envio de eventos. Para cada header é necessário informar:
    • Nome: Nome do header.
    • Valor: Valor do header.

Parâmetros de tipo de webhook: Azure Pipelines​

Os webhooks do tipo Azure Pipelines recebem os dados do evento em variáveis de ambiente acessíveis pelo pipeline.

Informação adicional

Por padrão, os pipelines construídos no Azure Pipelines limitam o recebimento de dados por variáveis a apenas as variáveis cadastradas no pipeline. Devido à quantidade de variáveis enviadas pelos webhooks do DHuO, é recomendado desabilitar essa restrição, porém é possível cadastrar cada variável manualmente. Caso não seja tomada nenhuma dessas ações, o evento não será recebido ou será rejeitado com erro pelo Azure Pipelines. Para desabilitar a restrição de variáveis:

  1. Acesse o projeto no Azure DevOps
  2. Acesse as configurações de pipelines do projeto em Project Settings > [Seção Pipelines] Settings
  3. Desabilite a opção Limit variables that can be set at queue time
  • Token: Obrigatório. Personal Access Token para acesso à API do Azure Pipelines. Deve possuir o scope Read & execute da categoria Build. Para gerar um token, acesse a página de configurações do usuário desejado, opção Personal access tokens. Em seguida, configure o token e adicione os escopos necessários. Copie o valor do token gerado e informe no cadastro do webhook.
  • Organization: Obrigatório. Nome da organização que possui o pipeline a receber eventos do DHuO. Pode ser obtido pela página de configurações da organização no Azure DevOps ou pela URL, após o host dev.azure.com. Exemplo: se a URL de acesso ao Azure DevOps é https://dev.azure.com/dhuo-org, a organização será dhuo-org.
  • Project: Obrigatório. Nome do projeto que possui o pipeline a receber eventos do DHuO. Pode ser obtido pela página de configurações do projeto no Azure DevOps ou pela URL, após o nome da organização. Exemplo: se a URL de acesso ao projeto no Azure DevOps é https://dev.azure.com/dhuo-org/my-project, o projeto será my-project.
  • Pipeline ID: Obrigatório. ID do pipeline cadastrado no Azure Pipelines para recebimento de eventos. Para obter o ID, acesse a lista de pipelines no Azure DevOps e selecione o pipeline desejado. O ID do pipeline estará na URL, no parâmetro definitionId. Exemplo: se a URL do pipeline é https://dev.azure.com/dhuo-org/my-project/_build?definitionId=1, o ID do pipeline será 1.
  • Stages ignorados: Lista opcional de stages do pipeline a serem ignorados da execução quando receber eventos do DHuO.
  • Variáveis: Lista de variáveis opcionais que serão adicionadas com as variáveis enviadas com os dados dos eventos do DHuO. Para cada variável é necessário informar:
    • Nome: Nome da variável.
    • Valor: Valor da variável.
    • Variável secreta: Informa se a variável é secreta. Variáveis secretas tem seus valores ocultados nos logs de execução do Azure Pipelines.

Parâmetros de tipo de webhook: GitLab CI/CD​

Os webhooks do tipo GitLab CI/CD recebem os dados do evento em variáveis de ambiente acessíveis pelo pipeline CI/CD.

  • Token: Obrigatório. Pipeline trigger token para acesso à API do GitLab. Esses tokens são vinculados ao projeto/repositório que o pipeline pertence. O token deve ser gerado por um usuário com permissões de execução de pipeline no repositório desejado. Para gerar um token, acesse a página de configurações CI/CD do projeto com o pipeline, seção Pipeline trigger tokens. Em seguida, configure o token e adicione os escopos necessários. Copie o valor do token gerado e informe no cadastro do webhook.
  • GitLab URL: Obrigatório. URL de acesso à instância do GitLab, como https://gitlab.com ou a instância pessoal hospedada.
  • Project ID: Obrigatório. ID do projeto no GitLab. Para obter o ID, acesse a página de configurações gerais do repositório no GitLab. O ID estará na configuração Project ID.
  • Nome da branch ou tag: Nome da branch ou tag que disparará o pipeline com o recebimento dos eventos enviados pelo DHuO.
  • Variáveis: Lista de variáveis opcionais que serão adicionadas com as variáveis enviadas com os dados dos eventos do DHuO. Para cada variável é necessário informar:
    • Nome: Nome da variável.
    • Valor: Valor da variável.

Exemplos de eventos​

Aqui estão os campos enviados para cada tipo de evento de webhook, nos formatos JSON (webhook genérico) e o nome das variáveis de ambiente correspondentes (webhooks Azure Pipelines e GitLab CI/CD):

Integration Release​

JSON

{
  "webhook": {
    "id": "00000000-0000-0000-0000-000000000000",
    "eventTrigger": "INTEGRATION_RELEASE",
    "eventOperation": "CREATE",
    "eventOperationStatus": "SUCCESS",
    "eventDate": "2025-02-01T19:32:02.824Z"
  },
  "integration": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "dhuo-test-integration"
  },
  "integrationVersion": {
    "id": "22222222-2222-2222-2222-222222222222",
    "version": "v1.0.0"
  },
  "release": {
    "id": "33333333-3333-3333-3333-333333333333",
    "name": "r1"
  },
  "status": "SUCCESS",
  "dockerImage": "registry-dhuo.fake.io/org/wks/dhuo-test-integration-v1-0-0:r1",
  "errorLog": "",
  "author": {
    "name": "John Doe",
    "email": "john.doe@dhuo.io"
  }
}

Variáveis de ambiente

"WEBHOOK_ID": "00000000-0000-0000-0000-000000000000"
"WEBHOOK_EVENT_TRIGGER": "INTEGRATION_DEPLOY"
"WEBHOOK_EVENT_OPERATION": "CREATE"
"WEBHOOK_EVENT_OPERATION_STATUS": "SUCCESS"
"WEBHOOK_EVENT_DATE": "2025-02-01T19:36:55.770Z"
"INTEGRATION_ID": "11111111-1111-1111-1111-111111111111"
"INTEGRATION_NAME": "dhuo-test-integration"
"INTEGRATION_VERSION_ID": "22222222-2222-2222-2222-222222222222"
"INTEGRATION_VERSION": "v1.0.0"
"RELEASE_ID": "33333333-3333-3333-3333-333333333333"
"RELEASE_NAME": "r1"
"RELEASE_STATUS": "SUCCESS"
"DOCKER_IMAGE": "registry-dhuo.fake.io/org/wks/dhuo-test-integration-v1-0-0:r1"
"ERROR_LOG": ""
"AUTHOR_NAME": "John Doe"
"AUTHOR_EMAIL": "john.doe@dhuo.io"

Integration Deploy​

JSON

{
  "webhook": {
    "id": "00000000-0000-0000-0000-000000000000",
    "eventTrigger": "INTEGRATION_DEPLOY",
    "eventOperation": "CREATE",
    "eventOperationStatus": "SUCCESS",
    "eventDate": "2025-02-01T19:33:41.526Z"
  },
  "integration": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "dhuo-test-integration"
  },
  "integrationVersion": {
    "id": "22222222-2222-2222-2222-222222222222",
    "version": "v1.0.0"
  },
  "release": {
    "id": "33333333-3333-3333-3333-333333333333",
    "name": "r1"
  },
  "environment": {
    "id": "44444444-4444-4444-4444-444444444444",
    "name": "Test"
  },
  "cluster": {
    "id": "55555555-5555-5555-5555-555555555555",
    "name": "Test Cluster",
    "type": "GKE",
    "region": "us-east1",
    "namespace": "tst"
  },
  "deployment": {
    "id": "99999999-9999-9999-9999-999999999999"
  },
  "status": "SUCCESS",
  "dockerImage": "registry-dhuo.fake.io/org/wks/dhuo-test-integration-v1-0-0:r1",
  "serviceAddress": "http://service-dhuo-test-integration-v1.tst/run",
  "errorLog": "",
  "author": {
    "name": "John Doe",
    "email": "john.doe@dhuo.io"
  }
}

Variáveis de ambiente

"WEBHOOK_ID": "00000000-0000-0000-0000-000000000000"
"WEBHOOK_EVENT_TRIGGER": "INTEGRATION_DEPLOY"
"WEBHOOK_EVENT_OPERATION": "CREATE"
"WEBHOOK_EVENT_OPERATION_STATUS": "SUCCESS"
"WEBHOOK_EVENT_DATE": "2025-02-01T19:35:46.289Z"
"INTEGRATION_ID": "11111111-1111-1111-1111-111111111111"
"INTEGRATION_NAME": "dhuo-test-integration"
"INTEGRATION_VERSION_ID": "22222222-2222-2222-2222-222222222222"
"INTEGRATION_VERSION": "v1.0.0"
"RELEASE_ID": "33333333-3333-3333-3333-333333333333"
"RELEASE_NAME": "r1"
"ENVIRONMENT_ID": "44444444-4444-4444-4444-444444444444"
"ENVIRONMENT_NAME": "Test"
"CLUSTER_ID": "55555555-5555-5555-5555-555555555555"
"CLUSTER_NAME": "Test Cluster"
"CLUSTER_TYPE": "GKE"
"CLUSTER_REGION": "us-east1"
"CLUSTER_NAMESPACE": "tst"
"DEPLOYMENT_ID": "99999999-9999-9999-9999-999999999999"
"DEPLOY_STATUS": "SUCCESS"
"DOCKER_IMAGE": "registry-dhuo.fake.io/org/wks/dhuo-test-integration-v1-0-0:r1"
"SERVICE_ADDRESS": "http://service-dhuo-test-integration-v1.tst/run"
"ERROR_LOG": ""
"AUTHOR_NAME": "John Doe"
"AUTHOR_EMAIL": "john.doe@dhuo.io"