# Notificações Proxmox no celular: backups, fencing, replicação e erros de disco

> Envie notificações do Proxmox VE e do Proxmox Backup Server para iPhone e Android usando o destino webhook integrado. Backups com falha chegam em alto, os bem-sucedidos em silêncio, um nó isolado (fenced) te acorda, e os avisos do smartd e do ZFS deixam de morrer na caixa de correio do root.

*25.10.2026*

<!-- source: https://pocketalert.app/pt/blog/proxmox-alerts -->

A maioria dos hosts Proxmox envia suas notificações para `root@pam`, ou seja, um endereço de e-mail digitado no instalador anos atrás, entregue por um Postfix que nunca recebeu um relay. O backup noturno falha, o e-mail vai para uma fila local, e você descobre três semanas depois, quando precisa restaurar uma VM.

A outra configuração comum funciona, mas acaba sendo ignorada. Cada job de backup envia um e-mail longo todas as noites, todos dizem "sucesso", e o que diz "falha" parece exatamente igual aos outros trinta na pasta.

Desde o Proxmox VE 8.3 e o Proxmox Backup Server 3.3, o sistema de notificações tem um destino **webhook** genérico. Ele pode chamar qualquer API HTTP com um corpo que você mesmo escreve, então pode enviar um push direto para o seu celular, com prioridades diferentes para falhas e sucessos. Sem script no host e sem relay para manter.

## O que você precisa

- Proxmox VE 8.3 ou mais recente (qualquer 9.x funciona), ou Proxmox Backup Server 3.3 ou mais recente. Versões antigas são cobertas mais adiante.
- O app Pocket Alert no [iPhone ou Android](/get-app) e uma chave de API em [Chaves de API](/account/apikeys).
- Acesso a Datacenter → Notifications como `root@pam` ou a um usuário com `Mapping.Modify` em `/mapping/notifications`.

## O que o Proxmox pode te avisar

O Proxmox VE emite estes eventos, cada um com um `type`, uma severidade e alguns campos de metadados:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento</th><th><code>type</code></th><th>Severidade</th></tr></thead>
<tbody>
<tr><th>Backup concluído</th><td><code>vzdump</code></td><td><code>info</code></td></tr>
<tr><th>Backup falhou</th><td><code>vzdump</code></td><td><code>error</code></td></tr>
<tr><th>Job de replicação de storage falhou</th><td><code>replication</code></td><td><code>error</code></td></tr>
<tr><th>Nó do cluster isolado (fenced)</th><td><code>fencing</code></td><td><code>error</code></td></tr>
<tr><th>Atualizações do sistema disponíveis</th><td><code>package-updates</code></td><td><code>info</code></td></tr>
<tr><th>E-mail para root (smartd, ZFS ZED e outros)</th><td><code>system-mail</code></td><td><code>unknown</code></td></tr>
</tbody>
</table>
</div>

A última linha importa mais do que parece. O `smartd` verifica seus discos a cada 30 minutos e envia e-mail para o root quando um começa a falhar, e o daemon de eventos do ZFS envia e-mail para o root sobre pools degradados e erros de scrub (`ZED_EMAIL_ADDR="root"` é o padrão). O Proxmox transforma esses e-mails em eventos `system-mail`, então o mesmo webhook que informa backups também informa um disco morrendo.

## Configure o destino webhook

Na interface web, vá em **Datacenter → Notifications** e, em **Notification Targets**, clique em **Add → Webhook**. Preencha assim:

- **Endpoint Name:** `pocketalert`
- **Method/URL:** `POST` e `https://api.pocketalert.app/v1/messages`
- **Headers:** `Content-Type` = `application/json`, e `Token` = `{{ secrets.token }}`
- **Secrets:** `token` = sua chave de API do Pocket Alert

E o **Body**:

```
{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}
```

Algumas coisas estão acontecendo aqui:

- **`{{ json title }}` renderiza o valor como uma string JSON completa**, incluindo as aspas. Relatórios de backup são tabelas com várias linhas, e colocar `{{ message }}` entre aspas quebraria o JSON na primeira quebra de linha. O Proxmox também tem `{{ escape message }}`, que faz o mesmo sem as aspas ao redor.
- **A chave é um segredo.** Os segredos ficam armazenados em `/etc/pve/priv/notifications.cfg`, legível apenas pelo root, e a API nunca retorna seus valores. O Proxmox também os mascara em suas mensagens de erro.
- **O nível segue a severidade.** O Proxmox renderiza o body com Handlebars, que tem `if`, `eq` e `or`. Falhas de backup, falhas de replicação, fencing e e-mails de disco chegam como `high`, que atravessa o Foco no iPhone. Backups bem-sucedidos e avisos de atualização chegam como `low`: eles estão no feed se você quiser vê-los, mas não vibram.

Salve o destino e clique em **Test**. Uma notificação de teste deve chegar em poucos segundos.

O destino não faz nada até que um matcher direcione eventos para ele. Em **Notification Matchers**, clique em **Add**, dê o nome `pocketalert-all` e, na aba **Targets to notify**, marque `pocketalert`. Um matcher sem regras corresponde a todos os eventos.

### A mesma coisa pelo shell

Se você prefere a CLI, ou gerencia vários clusters, o `pvesh` faz o mesmo. Os valores dos headers, o body e os segredos são passados codificados em base64:

```bash
PA_KEY='your-api-key'
BODY='{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}'
b64() { printf '%s' "$1" | base64 -w0; }

pvesh create /cluster/notifications/endpoints/webhook \
  --name pocketalert --method post \
  --url https://api.pocketalert.app/v1/messages \
  --header "name=Content-Type,value=$(b64 application/json)" \
  --header "name=Token,value=$(b64 '{{ secrets.token }}')" \
  --secret "name=token,value=$(b64 "$PA_KEY")" \
  --body "$(b64 "$BODY")"

pvesh create /cluster/notifications/matchers --name pocketalert-all --target pocketalert
pvesh create /cluster/notifications/targets/pocketalert/test
```

O resultado fica em `/etc/pve/notifications.cfg`, que é compartilhado entre o cluster, então uma única configuração cobre todos os nós (o body em base64 foi encurtado aqui):

```
webhook: pocketalert
	method post
	url https://api.pocketalert.app/v1/messages
	header name=Content-Type,value=YXBwbGljYXRpb24vanNvbg==
	header name=Token,value=e3sgc2VjcmV0cy50b2tlbiB9fQ==
	body ewogICJ0aXRsZSI6IHt7IGpzb24gdGl0bGUgfX0s...

matcher: pocketalert-all
	target pocketalert
```

A chave em si fica em `/etc/pve/priv/notifications.cfg` como `secret name=token,value=<base64>`.

## Segundo nível: um nó isolado deve te acordar

Um backup com falha pode esperar até de manhã. Um nó isolado significa que o HA acabou de derrubar um host, e isso vale um push `critical` que atravessa o Não perturbe. Os matchers podem fazer isso sem mexer no template do body.

Crie um segundo destino webhook, `pocketalert-critical`, idêntico ao primeiro exceto por uma linha do body:

```
  "level": "critical"
```

Depois substitua o matcher geral por dois que se separam pelo tipo do evento:

```
matcher: pocketalert-all
	match-field exact:type=fencing
	invert-match true
	target pocketalert

matcher: pocketalert-fencing
	match-field exact:type=fencing
	target pocketalert-critical
```

O `invert-match` inverte o primeiro matcher, então o fencing vai apenas para o destino crítico e você não recebe dois pushes para o mesmo evento. A entrega `critical` através do Não perturbe é um recurso de plano pago; no plano gratuito ela chega como `high`. Veja [níveis de prioridade](https://info.pocketalert.app/features/priority-levels.html) para o que cada nível faz no iOS e no Android.

Mais coisas para as quais os matchers servem bem:

- **Somente falhas.** Adicione `match-severity error,unknown` ao `pocketalert-all` e os backups bem-sucedidos param de enviar qualquer coisa. Nós os manteríamos como `low`: um "backup concluído" silencioso toda noite é a forma mais fácil de perceber quando ele para de chegar.
- **Um job.** `match-field exact:job-id=backup-abc123` limita um matcher a um único job agendado. Backups iniciados com **Run now** não têm `job-id`, então não correspondem.
- **Horário de silêncio.** `match-calendar mon..fri 9-17` limita um matcher ao horário de trabalho, e `invert-match` te dá o resto.

### Um botão que abre a interface web

Os pushes do Pocket Alert podem carregar até três [botões de ação](https://info.pocketalert.app/features/action-buttons.html). Adicione um ao body e um backup com falha abre a interface do Proxmox com um toque:

```
  "actions": [
    {"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
  ]
```

O telefone abre a URL diretamente, então um endereço local funciona sempre que você estiver na sua rede doméstica ou na VPN.

## Proxmox Backup Server

O PBS 3.3 e mais recentes têm o mesmo sistema de notificações em **Configuration → Notifications**, com o mesmo destino webhook, o mesmo body e os mesmos helpers do Handlebars. Sua configuração fica em `notifications.cfg` e `notifications-priv.cfg` em `/etc/proxmox-backup/`.

Os eventos são diferentes e mais úteis para um servidor de backup: garbage collection (`gc`), `prune`, `sync`, `verification`, `tape-backup` e `tape-load`, além de falhas na renovação de certificados `acme` e `package-updates`. O `acme` só reporta falhas e o `tape-load` é um `notice`; os demais vêm nas versões `info` e `error`, então o mesmo `if` no body funciona sem alterações. Os eventos de datastore (`gc`, `prune`, `sync`, `verification`, `tape-backup`) também carregam um campo `datastore`, então `match-field regex:datastore=^offsite-.*$` pode enviar datastores offsite para outro destino.

Dois detalhes do PBS para conferir. Datastores criados antes do sistema de notificações podem ter um `notification-mode` que ainda seja `legacy-sendmail`; mude para o sistema de notificações nas opções do datastore. E o PBS só envia notificações de `package-updates` em hosts com assinatura ativa.

## Limites honestos

- **O host precisa estar online para reportar.** O webhook é enviado pelo próprio host Proxmox, então se ele perdeu o link de rede ou está desligado, nada sai. Para "a máquina inteira está fora", você precisa de uma verificação externa, como um monitor de uptime em outra máquina.
- **Relatórios longos de backup são cortados no push.** Um backup de vinte convidados gera uma tabela longa. O push mostra cerca de 3 KB do início; o texto completo está no histórico de mensagens do app.
- **`system-mail` é tudo que é enviado para o root.** Isso inclui smartd e ZFS, mas também a saída do cron e qualquer outra coisa que envie e-mail para o root no seu sistema. Se ficar barulhento, dê a esses eventos um matcher próprio com `match-field exact:type=system-mail` e um destino mais silencioso.
- **Sem compatibilidade com Gotify.** O Proxmox também tem um destino Gotify integrado, e guias antigos o usam para pushes no celular. O Pocket Alert não implementa a API do Gotify, então esse destino não pode apontar para nós. Use o destino webhook acima, ou veja [como o Pocket Alert se compara ao Gotify](/alternatives/gotify).

## No Proxmox VE 8.2 e anteriores

Atualizar é a melhor solução, já que o destino webhook exige a 8.3. Se você ainda não pode atualizar, um script hook do vzdump cobre o caso mais importante, os backups. Instale a [CLI do Pocket Alert](/tools/cli) no nó como root, rode `pocketalert auth` e salve isto como `/usr/local/bin/vzdump-pocketalert`:

```bash
#!/bin/sh
case "$1" in
  backup-abort) pocketalert send -t "Backup failed: $3 on $(hostname)" -m "Mode: $2" -l high ;;
  job-end)      pocketalert send -t "Backup job finished on $(hostname)" -m "Check the task log for details" -l low ;;
esac
exit 0
```

Torne-o executável e adicione `script: /usr/local/bin/vzdump-pocketalert` ao `/etc/vzdump.conf`. O vzdump o chama em cada fase; para `backup-abort`, o segundo e o terceiro argumentos são o modo do backup e o ID da VM.

## Se nada chegar

- **Execute o Test primeiro.** Se o push de teste chega mas os eventos reais não, o destino está correto e o problema é o roteamento: verifique se algum matcher cita o destino e se as regras dele correspondem.
- **Confira o modo de notificação do job de backup.** Um job com um endereço de e-mail nas configurações de notificação e o modo padrão `auto` usa o sendmail legado e ignora totalmente o sistema de notificações. Limpe o endereço ou defina o modo como sistema de notificações; em `/etc/pve/jobs.cfg` isso fica como `notification-mode notification-system`.
- **Leia o journal.** `journalctl --since "1 hour ago" | grep -i notif` mostra as requisições com falha. Um `401` significa que a chave está errada; um `400` geralmente significa que o body não é um JSON válido: confira se você usou `{{ json message }}` e não um `{{ message }}` solto.
- **Confira o feed no app.** Pushes `low` não fazem som, então um backup bem-sucedido pode parecer que nunca chegou. Ele está no histórico de mensagens.

## FAQ

### Preciso de uma assinatura do Proxmox?

Não. O sistema de notificações e o destino webhook fazem parte dos repositórios gratuitos. A única peça que depende de assinatura é a notificação de `package-updates` do PBS.

### Isso funciona para um nó único, sem cluster?

Sim. Um nó único lê o mesmo `/etc/pve/notifications.cfg`. Em um cluster o arquivo é compartilhado, então você configura uma vez só.

### Posso receber isso também por e-mail?

Sim. Mantenha o destino padrão `mail-to-root` no matcher e adicione `pocketalert` ao lado dele. Um matcher pode notificar vários destinos, e cada destino recebe a notificação no máximo uma vez.

### Quantos pushes isso vai usar?

Um por evento. Um job de backup noturno gera uma notificação para o job inteiro, não uma por convidado, então um homelab típico envia poucas por dia. O plano gratuito cobre 50 mensagens por dia em um dispositivo.

### E o TrueNAS, os eventos de energia do UPS ou o Uptime Kuma?

A mesma ideia, outro remetente. A página de [alertas para homelab](/use-cases/homelab-alerts) cobre as peças comuns de um rack de servidor doméstico, e [alertas de backup](/use-cases/backup-alerts) cobre ferramentas de backup fora do Proxmox.

[Crie uma conta gratuita](/signup), cole o body em um destino webhook e deixe que o próximo backup com falha encontre você, em vez da sua caixa de entrada.
