4 Webhook

Visão geral

O tipo de mídia webhook é útil para chamadas HTTP customizadas de código JavaScript para integração direta com software externos como sistemas de helpdesk, chats, ou mensageiros. Você pode escolher importar uma integração provida pelo Zabbix ou criar uma integração customizada do zero.

Integrações

As seguintes integrações estão disponíveis permitindo o uso de tipos de mídia webhook pré-definidos para envio de notificações Zabbix para:

Em adição aos serviços listados aqui, o Zabbix pode ser integrado com Spiceworks (nenhum webhook é necessário). Para converter notificações Zabbix em chamados do Spiceworks, crie um tipo de mídia email e informe o endereço de e-mail de helpdesk do Spiceworks (p.e. [email protected]) nas configurações de perfil de um usuário Zabbix designado.

Configuração

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

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

Para criar um webhook customizado do zero:

Vá até Administração → Tipos de mídia
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 estão marcados com um asterisco vermelho.

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

Parâmetro	Descrição
Parâmetros	Especifique as variáveis de webhook como pares de atributo e valor. Para webhooks pré-configurados, a lista de parâmetros varia, dependendo do serviço. Verifique o arquivo Readme.md do webhook para descrição de parâmetro. Para novos webhooks, várias variáveis comuns estão incluídas por padrão (URL:<vazio>, HTTPProxy:<vazio>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:%7BALERT.MESSAGE}), sinta-se à vontade para manter ou removê-las. Todas as macros que são suportadas nas notificações de problema são suportadas nos parâmetros. Se você especificar um proxy HTTP, o campo suporta as mesmas funcionalidades que o campo HTTP proxy da configuração de item. A string de proxy pode ser prefixada com `[scheme]://` para especificar qual tipo de proxy é usado (p.e. https, socks4, socks5; veja documentação).
Script	Informe o código JavaScript no bloco que aparece quando clicando no campo do parâmetro (ou no botão ver/editar próximo a ele). Este código executará a operação de webhook. O script é um código de função que aceita parâmetro - pares de 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, ele pode executar requisições HTTP de GET, POST, PUT e DELETE e tem controle sobre cabeçalhos e corpo de requisição HTTP. O script deve conter um operador de retorno, caso contrário ele não será válido. Ele pode retornar o estado OK em conjunto com uma lista opcional de etiquetas e valores de etiqueta (veja a opção Etiquetas de processo) ou uma string de erro. Note que o script é executado somente após um alerta ser criado. Se o script for configurado para retornar e processar etiquetas, estas etiquetas não serão resolvidas nas macros {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} na mensagem de problema inicial e mensagens de recuperação porque o script ainda não teve tempo de ser executado. Veja também: Diretrizes de desenvolvimento de Webhook, Exemplos de script de webhook, Objetos JavaScript adicionais.
Tempo limite	Tempo limite de execução do JavaScript (1-60s, padrão é 30s). Sufixos de tempo são suportados, p.e. 30s, 1m.
Etiquetas de processo*	Marque a caixa para processar os valores de propriedade JSON retornados como etiquetas. Estas etiquetas são adicionadas às etiquetas de evento de problema já existentes (se houver) no Zabbix. Se um webhook usa etiquetas (a caixa Processar etiquetas estiver marcada), o webhook deve sempre retornar um objeto JSON contendo ao menos um objeto vazio para etiquetas:`var result = {tags: {}};`. Exemplos de etiquetas que podem ser retornadas: Jira ID: PROD-1234, Responsável: John Smith, Processado:<sem valor>, etc.
Incluir entrada de menu de evento	Marque a caixa para incluir uma entrada no menu de evento associando-o ao chamado externo criado. Se marcado, o webhook não deve ser usado para enviar notificações para usuários diferentes (considere a criação de um usuário dedicado em vez disso) ou em várias ações de alerta relacionadas a um único evento de problema.
Nome da entrada de menu	Especifique o nome da entrada de menu. A macro {EVENT.TAGS.<nome etiqueta>} é suportada. Este campo é obrigatório apenas se Incluir entrada de menu de evento estiver selecionado.
URL de entrada de menu	Especifique a URL associada à entrada de menu. A macro {EVENT.TAGS.<nome etiqueta>} é suportada. Este campo é obrigatório apenas se Incluir entrada de menu de evento estiver selecionado.

Consulte os parâmetros de tipo de mídia comuns para detalhes em como configurar opções de mensagens padrão e processamento de alerta.

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

Media type testing

To test a configured webhook media type:

Locate the relevant webhook in the list of media types.
Click on Test in the last column of the list (a testing window will open).
Edit the webhook parameter values, if needed.
Click on Test.

By default, webhook tests are performed with parameters entered during configuration. However, it is possible to change attribute values for testing. Replacing or deleting values in the testing window affects the test procedure only, the actual webhook attribute values will remain unchanged.

To view media type test log entries without leaving the test window, click on Open log (a new popup window will open).

If the webhook test is successful:

"Media type test successful." message is displayed
Server response appears in the gray Response field
Response type (JSON or String) is specified below the Response field

If the webhook test fails:

"Media type test failed." message is displayed, followed by additional failure details.

Mídia de usuário

Uma vez que o tipo de mídia é configurado, vá até a seção Administração → Usuários e associe a mídia webhook para um usuário existente ou crie um novo usuário para representar o webhook. As etapas para configuração de mídia de usuário para um usuário existente, sendo comum para todos os tipos de mídia, estão descritas na página Tipos de mídia.

Se um webhook usa etiquetas para armazenar o ID de chamado\mensagem, evite associar o mesmo webhook como um mídia para diferentes usuários pois fazendo isto pode causar erros no webhook (se aplica à maioria dos webhooks que utilizam a opção Incluir entrada de menu de evento). Neste caso, a melhor prática é criar um usuário dedicado para representar o webhook:

Após a configuração do tipo de mídia webhook, vá até a seção Administração → Usuários e crie um usuário Zabbix dedicado para representar o webhook - por exemplo, com um usuário Slack para o webhook Slack. Todas as configurações, exceto mídia, podem ser deixadas em seu padrão pois este usuário não fará login no Zabbix.
No perfil de usuário, vá até a aba Mídia e adicione um webhook com as informações de contato necessárias. Se o webhook não usa um campo Enviar para, informe qualquer combinação de caracteres suportados para atender à validação de requisitos.
Garante a este usuário ao menos permissões de leitura para todos os hosts para os quais ele deve enviar os alertas.

Quando configurando um ação de alerta, adicione este usuário no campo Enviar para usuários nos detalhes de Operação - isto informará ao Zabbix para usar o webhook para notificação desta ação.

Configurando ações de alerta

Ações determinam que notificações devem ser enviadas através do webhook. As etapas para configuração de ações envolvendo webhooks são as mesmas para todos os tipos de mídia com estas exceções:

Se um webhook usa etiquetas para armazenar ID de chamado\mensagem e para acompanhar operações de atualização\solução, este webhook não deve ser usado em várias ações de alerta para um único evento de problema. Se {EVENT.TAGS.<nome>} já existir, e estiver atualizado no webhook, então seu valor resultante não é definido. Para tal caso, um novo nome de etiqueta deve ser usado no webhook para armazenar valores atualizados. Isto se aplica aos webhooks do Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad, e Zendesk fornecidos pela Zabbix e à maioria dos webhooks que utilizam a opção Incluir entrada no menu de evento. A utilização do webhook em várias operações é permitida se essas operações ou etapas de escalação pertencerem à mesma ação. É também possível usar este webhook em diferentes ações se as ações não serão aplicadas ao mesmo evento de problema devido condições de filtro diferentes.
Quando usando um webhook em ações para eventos internos: na configuração da operação da ação, verifique a caixa Mensagem customizada e defina a mensagem customizada, caso contrário, não será enviada uma notificação.

Documentation