Como instalar a integração Nvoip no Zabbix

Última atualização: 23/10/2026

Este manual ensina a instalar manualmente o Webhook Nvoip alerts no Zabbix para enviar alertas por SMS, WhatsApp ou chamada de voz usando a API v3 da Nvoip.

A instalação manual funciona mesmo enquanto a integração aguarda publicação no Marketplace oficial do Zabbix. O arquivo é importado no seu próprio servidor Zabbix e as notificações são enviadas diretamente para a API da Nvoip.

Antes de começar

Você precisa de:

• Zabbix 7.0 ou 7.4;
• uma conta Nvoip ativa;
• credenciais OAuth da API v3 criadas no Painel Nvoip;
• o canal que será usado habilitado na conta;
• templates de SMS ou WhatsApp aprovados, quando usar esses canais;
• uma origem de chamada permitida, quando usar chamada de voz;
• acesso administrativo ao Zabbix para importar e configurar tipos de mídia.

As credenciais OAuth devem permitir somente os canais utilizados. O pacote suporta estes escopos:

O arquivo distribuído pela Nvoip já solicita sms:send whatsapp:send call:make. Se sua operação usar apenas parte dos canais, remova somente os escopos que não serão utilizados.

Baixar o arquivo oficial

Baixe o arquivo media_nvoip.yaml na release oficial da Nvoip:

https://github.com/Nvoip/nvoip-zabbix/releases/tag/v1.1.0

Não copie credenciais para o arquivo YAML. Os campos sensíveis devem permanecer como macros secretas no Zabbix.

Importar no Zabbix

1. Entre no Zabbix com uma conta administrativa.
2. Acesse Alerts > Media types.
3. Clique em Import.
4. Selecione o arquivo media_nvoip.yaml.
5. Mantenha Create new marcado.
6. Confirme a importação.
7. Abra o tipo de mídia Nvoip alerts.

O pacote é importado desabilitado e com nvoip_dry_run=1. Importar o arquivo não envia mensagens nem realiza ligações.

Cadastrar as credenciais OAuth

Antes de configurar o Zabbix, siga o manual Como gerar credenciais OAuth da API v3 no Painel Nvoip. Crie uma credencial do tipo client_credentials e selecione somente os escopos dos canais que serão utilizados.

Cadastre estas macros como Secret text ou Vault secret:

O modo padrão é client_credentials. O Webhook obtém um token de curta duração em cada execução.

Nunca coloque o client ID, a credencial ou um token no assunto do alerta, na mensagem, no campo Send to, em prints ou em arquivos versionados.

Configurar o canal e o destinatário

Associe o tipo de mídia a um usuário do Zabbix. No campo Send to, informe o canal seguido do número em formato internacional, somente com dígitos:

sms:5511999999999
whatsapp:5511999999999
voice:5511999999999

O sinal + no início é opcional.

SMS

No Painel Nvoip, selecione e salve para a sua conta os templates aprovados:

• zabbix_problema;
• zabbix_recuperado;
• zabbix_atualizado.

Informe os IDs das cópias da sua conta nas macros:

O Webhook não usa texto livre como fallback. O template precisa estar ativo, aprovado e vinculado à mesma conta das credenciais OAuth.

WhatsApp

Configure:

O idioma padrão é pt_BR. Por padrão, o Webhook envia o assunto e a mensagem do alerta como duas variáveis de corpo. Se o template aprovado tiver outra quantidade ou ordem de variáveis, ajuste nvoip_whatsapp_body_1 até nvoip_whatsapp_body_6.

Chamada de voz

Configure {$NVOIP.VOICE.CALLER} com uma origem autorizada para a conta. Alertas de recuperação não geram chamada por padrão.

Testar sem enviar comunicação

Antes de ativar, mantenha nvoip_dry_run=1 e use Test no tipo de mídia.

Exemplo:

send_to=whatsapp:5511999999999
event_source=0
event_value=1
event_update_status=0
event_id=TESTE-ZABBIX
event_name=Teste de alerta
host_name=host-teste
event_severity=Warning
event_date=2026.10.23
event_time=12:00:00

O resultado esperado é status=dry_run. Nesse modo, o Webhook não autentica na API e não envia mensagem ou chamada.

Repita o teste com sms:, whatsapp: e voice: para conferir a configuração de cada canal que será utilizado.

Ativar com segurança

1. Confirme que todos os testes em dry-run passaram.
2. Verifique se nenhuma macro ainda mostra o placeholder {$NVOIP...}.
3. Mantenha attempts=1. Uma tentativa automática depois de uma resposta incerta pode repetir uma comunicação tarifável.
4. Altere nvoip_dry_run para 0.
5. Habilite Nvoip alerts.
6. Associe o tipo de mídia somente às actions e severidades desejadas.
7. Faça o primeiro envio real apenas para um destinatário controlado e autorizado.

status=sent confirma que a API aceitou a solicitação. Esse estado, sozinho, não comprova o recebimento no aparelho.

Configuração inicial recomendada

Configure equipes, horários e destinatários diferentes em usuários e operações separadas do Zabbix. Não grave destinatários dentro do Webhook.

Atualizar a integração

Antes de importar uma versão nova:

1. exporte o tipo de mídia atual como backup;
2. registre as macros e associações utilizadas sem copiar os valores secretos;
3. importe a nova versão com atualização do tipo existente;
4. confirme que nvoip_dry_run=1 durante o primeiro teste;
5. reative somente depois de validar a configuração.

Remover ou reverter

1. Desabilite as actions que usam Nvoip alerts.
2. Desabilite e remova o tipo de mídia.
3. Remova as macros secretas somente depois de confirmar que nenhuma outra integração as utiliza.

A instalação não exige migration, SQL, alteração de Security Group ou mudança de permissão de arquivos no servidor Zabbix.

Solução de problemas

Erro de escopo ou permissão no WhatsApp

Confirme que o cliente OAuth possui whatsapp:send, que a instância pertence à mesma conta e que o template está aprovado e ativo.

Macro obrigatória não configurada

Confira se todas as macros do canal foram criadas e se o valor não permaneceu como {$NVOIP...}.

SMS recusado com HTTP 200

O Webhook também valida a resposta funcional da API. Verifique se o template pertence à conta, está aprovado e recebe a quantidade correta de variáveis.

Erro temporário ou limite de requisições

Respostas 408, 425, 429 e 5xx são classificadas como temporárias. Confira o histórico da action e reconcilie o resultado antes de repetir manualmente, evitando comunicações duplicadas.

Suporte

Para confirmar os canais habilitados ou receber ajuda na configuração, abra um chamado na Central de Ajuda Nvoip:

https://suporte.nvoip.com.br/portal/pt/newticket

Projeto e histórico de versões:

https://github.com/Nvoip/nvoip-zabbix