4 Webhook

Visão geral

O tipo de mídia webhook é útil para fazer chamadas HTTP usando código JavaScript personalizado para integração direta com softwares externos, como sistemas de helpdesk, chats ou mensageiros. Você pode optar por importar uma integração fornecida pelo Zabbix ou criar uma integração personalizada do zero.

Integrações

As seguintes integrações estão disponíveis, permitindo usar tipos de mídia de webhook predefinidos para enviar notificações do Zabbix para:

Além dos serviços listados aqui, o Zabbix pode ser integrado ao Spiceworks (nenhum webhook é necessário). Para converter notificações do Zabbix em tickets do Spiceworks, crie um tipo de mídia de e-mail e informe o endereço de e-mail do helpdesk do Spiceworks (por exemplo, [email protected]) nas configurações de perfil de um usuário do Zabbix designado.

Configuração

Para começar a usar uma integração de webhook:

  1. Localize o arquivo .yaml necessário no diretório templates/media da versão baixada do Zabbix ou baixe-o do repositório git do Zabbix.
  2. Importe o arquivo para sua instalação do Zabbix. O webhook aparecerá na lista de tipos de mídia.
  3. Configure o webhook de acordo com as instruções no arquivo Readme.md (você pode clicar no nome de um webhook acima para acessar rapidamente o arquivo Readme.md).

Para criar um webhook personalizado do zero:

  1. Acesse Alertas > Tipos de mídia.
  2. Clique em Criar tipo de mídia.

A aba Tipo de mídia contém vários atributos específicos para este tipo de mídia:

Todos os campos de entrada obrigatórios são marcados com um asterisco vermelho.

Os parâmetros a seguir são específicos para o tipo de mídia webhook:

Parâmetro Descrição
Parâmetros Especifique as variáveis do webhook como pares de atributo e valor.
Para webhooks pré-configurados, a lista de parâmetros varia de acordo com o serviço. Consulte o arquivo Readme.md do webhook para obter a descrição dos parâmetros.
Para novos webhooks, várias variáveis comuns são incluídas por padrão (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); você pode mantê-las ou removê-las.

Os parâmetros do webhook são compatíveis com macros de usuário, todas as macros compatíveis com notificações de problemas e, adicionalmente, com as macros {ALERT.SENDTO}, {ALERT.SUBJECT} e {ALERT.MESSAGE}.

Se você especificar um proxy HTTP, o campo oferecerá a mesma funcionalidade que o campo proxy HTTP na configuração do item. A string do proxy pode ser prefixada com [scheme]:// para especificar o tipo de proxy usado (por exemplo, https, socks4, socks5; consulte a documentação).
Script Insira o código JavaScript no editor modal que é aberto ao clicar no campo de parâmetro ou no ícone de lápis ao lado dele. Esse código executará a operação do webhook.
O script é um código de função que aceita pares de parâmetro e valor. Os valores devem ser convertidos em objetos JSON usando o método JSON.parse(), por exemplo: var params = JSON.parse(value);.

O código tem acesso a todos os parâmetros, pode executar solicitações HTTP GET, POST, PUT e DELETE, oferecer suporte a métodos adicionais, como CONNECT, PATCH, HEAD, OPTIONS e TRACE, e controlar os cabeçalhos HTTP e o corpo da solicitação.
O script deve conter um operador return; caso contrário, não será válido. Ele pode retornar o status OK junto com uma lista opcional de tags e valores de tags (consulte a opção Processar tags) ou uma string de erro.

Observe que o script é executado somente depois que um alerta é criado. Se o script estiver configurado para retornar e processar tags, essas tags não serão resolvidas nas macros {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} da mensagem inicial do problema e das mensagens de recuperação, pois o script ainda não terá tido tempo de ser executado.
Observação: é recomendável usar variáveis locais (por exemplo, var local = 1) em vez de uma variável global (por exemplo, global = 1) para garantir que cada script opere sobre seus próprios dados e evitar colisões entre chamadas simultâneas (consulte os problemas conhecidos).

Consulte também: Diretrizes de desenvolvimento de webhook, Exemplos de scripts de webhook, Objetos JavaScript adicionais.
Tempo limite Tempo limite de execução do JavaScript (1-60s, padrão: 30s).
Sufixos de tempo são compatíveis (por exemplo, 30s, 1m).
Processar tags Marque a caixa de seleção para processar os valores das propriedades JSON retornadas como tags. Essas tags são adicionadas a quaisquer tags de problema existentes.
Observe que, ao usar tags de webhook, o webhook deve retornar um objeto JSON contendo pelo menos um objeto de tags vazio: var result = {tags: {}};
Exemplos de tags que podem ser retornadas: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Incluir entrada no menu de eventos Marque a caixa de seleção para incluir uma entrada no menu de eventos com um link para um ticket externo criado.
Uma entrada será incluída para cada webhook habilitado que tenha esta caixa de seleção marcada. Observe que, se os parâmetros Nome da entrada do menu e URL da entrada do menu contiverem macros {EVENT.TAGS.<tag name>}, uma entrada será incluída somente se essas macros puderem ser resolvidas (ou seja, se o evento tiver essas tags definidas).
Se marcada, o webhook não deverá ser usado para enviar notificações a usuários diferentes (considere criar um usuário dedicado) e não deverá ser usado em várias ações de alerta para um único evento de problema.
Nome da entrada do menu Especifique o nome da entrada do menu.
A macro {EVENT.TAGS.<tag name>} é compatível.
Este campo só é obrigatório se Incluir entrada no menu de eventos estiver marcado.
URL da entrada do menu Especifique a URL subjacente da entrada do menu.
A macro {EVENT.TAGS.<tag name>} é compatível.
Este campo só é obrigatório se Incluir entrada no menu de eventos estiver marcado.

Consulte parâmetros comuns de tipos de mídia para obter detalhes sobre como configurar mensagens padrão e opções de processamento de alertas.

Mesmo que um webhook não use mensagens padrão, os templates de mensagem para os tipos de operação usados por esse webhook ainda deverão ser definidos.

Teste

Para testar um tipo de mídia webhook configurado:

  1. Localize o webhook relevante na lista de tipos de mídia.
  2. Clique em Test na última coluna da lista (uma janela de teste será aberta).
  3. Edite os valores dos parâmetros do webhook conforme necessário. Substitua macros por valores de exemplo; caso contrário, as macros não serão resolvidas e o teste falhará.
  4. Clique em Test.

Substituir ou excluir valores na janela de teste afeta apenas o procedimento de teste; os valores reais dos atributos do webhook permanecerão inalterados.

Para visualizar as entradas do log de teste do tipo de mídia sem sair da janela de teste, clique em Open log (uma nova janela pop-up será aberta).

Se o teste do webhook for bem-sucedido:

  • A mensagem "Teste do tipo de mídia bem-sucedido." é exibida.
  • A resposta do servidor aparece no campo cinza Resposta.
  • O tipo de resposta (JSON ou String) é especificado abaixo do campo Resposta.

Se o teste do webhook falhar:

  • A mensagem "Media type test failed." é exibida, seguida de detalhes adicionais sobre a falha.

Mídia do usuário

Depois que o tipo de mídia estiver configurado, vá para a seção Usuários > Usuários e atribua a mídia webhook a um usuário existente ou crie um novo usuário para representar o webhook. As etapas para configurar a mídia do usuário para um usuário existente, por serem comuns a todos os tipos de mídia, estão descritas na página Tipos de mídia.

Se um webhook usar tags para armazenar o ID do ticket\mensagem, evite atribuir o mesmo webhook como mídia a usuários diferentes, pois isso pode causar erros de webhook (aplica-se à maioria dos webhooks que utilizam a opção Include event menu entry). Nesse caso, a prática recomendada é criar um usuário dedicado para representar o webhook:

  1. Após configurar o tipo de mídia webhook, vá para a seção Usuários > Usuários e crie um usuário dedicado do Zabbix para representar o webhook - por exemplo, com o nome de usuário Slack para o webhook do Slack. Todas as configurações, exceto mídia, podem ser mantidas com seus valores padrão, pois esse usuário não fará login no Zabbix.
  2. No perfil do usuário, vá para a aba Mídia e adicione um webhook com as informações de contato necessárias. Se o webhook não usar um campo Send to, insira qualquer combinação de caracteres suportados para ignorar os requisitos de validação.
  3. Conceda a esse usuário pelo menos permissões de leitura para todos os hosts para os quais ele deve enviar os alertas.

Ao configurar a ação de alerta, adicione esse usuário no campo Send to users em Detalhes da operação - isso instruirá o Zabbix a usar o webhook para notificações dessa ação.

Configurando ações de alerta

As ações determinam quais notificações devem ser enviadas via webhook. Os passos para configurar ações envolvendo webhooks são os mesmos que para todos os outros tipos de mídia, com estas exceções:

  • Se um webhook usa tags de webhook para armazenar o ID do ticket\mensagem e lidar com operações de atualização\resolução, evite usar o mesmo webhook em várias ações de alerta para um único evento de problema. Se {EVENT.TAGS.<tag name>} existir e for atualizada no webhook, seu valor resultante será indefinido. Para evitar isso, use um novo nome de tag no webhook para armazenar valores atualizados. Isso se aplica aos webhooks Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad e Zendesk fornecidos pelo Zabbix e à maioria dos webhooks que utilizam a opção Incluir entrada de menu de evento. Observe, no entanto, que um único webhook pode ser usado em várias operações ou etapas de escalonamento da mesma ação, bem como em diferentes ações que não serão acionadas pelo mesmo evento de problema devido a diferentes condições.
  • Ao usar um webhook em ações para eventos internos, certifique-se de marcar a caixa de seleção Mensagem personalizada e definir uma mensagem personalizada na configuração da operação da ação. Caso contrário, uma notificação não será enviada.