# Notificações push para Klipper: alertas de impressão no celular

> Receba uma notificação push quando uma impressão no Klipper terminar, falhar ou pausar. Notificador nativo do Moonraker mais um webhook do Pocket Alert, sem plugins, com um bloco de configuração.

*09.10.2026*

<!-- source: https://pocketalert.app/pt/blog/klipper-print-notifications -->

Uma impressão de doze horas não precisa que você fique ao lado dela. Ela precisa que você saiba no momento em que termina e, mais importante, no momento em que para.

O Klipper já consegue avisar sobre as duas coisas. O Moonraker, o servidor de API por trás do Mainsail e do Fluidd, tem um notificador nativo que dispara em eventos de impressão e envia essas mensagens pelo [Apprise](https://github.com/caronc/apprise). Aponte-o para um webhook do Pocket Alert e cada impressão concluída, com falha, cancelada ou pausada chega ao seu celular como notificação push. Sem plugin, sem serviço extra no Pi, com um bloco de configuração.

## O que você precisa

- Uma impressora rodando Klipper com Moonraker. Se você abre o Mainsail ou o Fluidd no navegador, já tem o Moonraker.
- Uma conta gratuita no [Pocket Alert](/) e o aplicativo no seu celular [iPhone ou Android](/get-app).
- Uns cinco minutos.

## Passo 1. Crie um webhook no Pocket Alert

Abra [Webhooks](/webhooks) no painel e crie um novo:

- **Nome**: a impressora, por exemplo `Voron 2.4`. O nome vira o título da push (`Webhook Voron 2.4`), então, com mais de uma impressora, você vê de relance qual precisa de você.
- **Aplicativo** e **Dispositivo**: para onde a notificação vai.
- **Mensagem**: cole este modelo:

```
%title%
%message%
```

Salve e copie a URL do webhook. Ela tem este formato: `https://p4a.me/wh/<your-webhook-id>`.

Por que este modelo: o Moonraker entrega cada notificação ao Apprise, e o notificador JSON do Apprise envia um payload pequeno como este:

```json
{
  "version": "1.0",
  "title": "❌ Print error",
  "message": "3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]",
  "attachments": [],
  "type": "info",
  "level": "high"
}
```

Cada `%key%` no modelo é substituída pelo campo correspondente do JSON. A push mostra o título na primeira linha e a mensagem embaixo. Mais sobre caminhos de modelo em [Crie sua primeira URL de webhook](/blog/create-your-first-webhook-url).

## Passo 2. Adicione os notificadores ao moonraker.conf

Abra o `moonraker.conf` (em **Machine** no Mainsail, em **Configuration** no Fluidd) e adicione estas três seções no final. Substitua `YOUR_WEBHOOK_ID` pelo id da URL do seu webhook.

```ini
[notifier pocketalert_done]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID
events: complete
title: ✅ Print complete
body: {event_args[1].filename}

[notifier pocketalert_fail]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: error, cancelled
title: ❌ Print {event_name}
body: {event_args[1].filename} {event_args[1].message}

[notifier pocketalert_pause]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: paused
title: ⏸ Print paused
body: {event_args[1].filename}: check the printer
```

O que cada parte faz:

- **`jsons://`** é o notificador JSON do Apprise sobre HTTPS. Ele envia o payload acima para o seu webhook.
- **`events`** escolhe os estados de impressão que disparam uma seção. O Moonraker conhece `started`, `complete`, `error`, `cancelled`, `paused` e `resumed`.
- **`?:level=high`** instrui o Apprise a adicionar `"level": "high"` ao JSON. O Pocket Alert lê esse campo e envia a push com prioridade alta, que no iPhone chega como notificação sensível ao tempo e atravessa os modos Foco. A seção "complete" não tem nível, então chega como push normal.
- **`{event_args[1]}`** é o estado do trabalho após o evento. Ele espelha o objeto `print_stats` do Klipper: `filename` é o arquivo G-code, `message` é o texto de erro do Klipper quando uma impressão falha.
- **`{event_name}`** é o evento que disparou, então uma seção cobre `error` e `cancelled` e o título ainda diz qual dos dois aconteceu.

## Passo 3. Reinicie o Moonraker e teste

Reinicie o Moonraker pelo menu de energia no Mainsail ou no Fluidd, ou por SSH:

```bash
sudo systemctl restart moonraker
```

Antes de gastar filamento num teste, verifique o webhook com curl. Isso envia o mesmo formato de JSON que o Apprise envia:

```bash
curl -X POST https://p4a.me/wh/YOUR_WEBHOOK_ID \
  -H 'Content-Type: application/json' \
  -d '{"title":"❌ Print error","message":"test.gcode Move out of range","level":"high"}'
```

Se o celular vibrar, a parte do Pocket Alert está funcionando. Agora inicie uma impressão pequena e cancele depois da primeira camada: você deve receber `❌ Print cancelled` em poucos segundos.

## O que chega no seu celular

Uma impressão com falha à noite aparece assim na tela de bloqueio:

```
Webhook Voron 2.4
❌ Print error
3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]
```

Você sabe qual impressora, qual arquivo e por que parou antes de desbloquear o celular.

## Personalize do seu jeito

Tudo abaixo é uma pequena edição no mesmo arquivo.

- **Registre o início das impressões sem barulho.** Adicione uma seção com `events: started` e `?:level=silent`. O início fica registrado no seu histórico de mensagens sem som.
- **Seja acordado por falhas.** Troque `?:level=high` por `?:level=critical` na seção de falhas. No Android, um alerta crítico fura o Não perturbe. A entrega crítica é um recurso pago; no plano gratuito, a mensagem ainda chega com prioridade alta. Detalhes em [alertas críticos](/use-cases/critical-alerts).
- **Várias impressoras.** Um webhook por impressora, cada um com o nome da máquina. O título da push mostra qual parou.
- **Alertas das suas próprias macros.** O Moonraker também tem o evento `gcode`, então uma macro do Klipper pode enviar qualquer texto que você quiser. Útil para troca de filamento ou sensor de fim de filamento.

No `moonraker.conf`:

```ini
[notifier pocketalert_macro]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: gcode
title: 🧵 Printer needs you
body: {event_message}
```

No `printer.cfg`:

```ini
[gcode_macro NOTIFY_FILAMENT_CHANGE]
gcode:
  {action_call_remote_method("notify",
                             name="pocketalert_macro",
                             message="Filament change needed")}
```

Chame `NOTIFY_FILAMENT_CHANGE` a partir da sua macro `M600` ou do `runout_gcode` de um sensor de filamento.

## Se nada chegar

- **Abra o webhook no painel.** O [histórico de webhooks](/features/webhook-history) registra cada chamada com o payload bruto. Sem registro significa que o Moonraker nunca chegou ao Pocket Alert. Um registro com erro mostra o motivo.
- **Leia o `moonraker.log`.** O Moonraker grava os erros do notificador ali, junto com a versão instalada do Apprise. Na maioria das instalações ele fica em `~/printer_data/logs/moonraker.log`.
- **Linhas vazias na push.** As chaves do modelo precisam bater com o payload do Apprise: `%title%` e `%message%`, não `%body%`.

## Por que não um plugin?

Bots do Telegram e serviços de acesso remoto para Klipper fazem mais: fotos da câmera, timelapses, controle remoto. Eles também adicionam mais um serviço no Pi para instalar e manter atualizado. Se o que você quer é "me avise quando terminar, me acorde se falhar", o Moonraker já faz o envio. O Pocket Alert só precisa receber.

E se a impressora fica perto de um [homelab](/use-cases/homelab-alerts), os alertas dela caem no mesmo aplicativo que os alertas do seu servidor, de backup e de tarefas cron, com um único histórico e os mesmos níveis de prioridade.

## FAQ

### Preciso instalar algo no Raspberry Pi?

Não. O notificador faz parte do Moonraker, e o Apprise é instalado junto como dependência. Você só edita o `moonraker.conf` e reinicia o Moonraker.

### Funciona com Mainsail e Fluidd?

Sim. Ambos são interfaces web do Moonraker, e o notificador fica no Moonraker, então a configuração é idêntica. Você pode editar o `moonraker.conf` por qualquer uma delas.

### Posso receber notificações de várias impressoras?

Sim. Crie um webhook por impressora e dê a ele o nome da máquina. O nome do webhook vira o título da push.

### Uma falha de impressão vai me acordar à noite?

Com `level=high`, a push chega como sensível ao tempo no iPhone e atravessa o Foco. Para furar o Não perturbe no Android, use `level=critical` em um plano pago.

### É gratuito?

Sim. Webhooks funcionam no plano gratuito, e cada evento usa uma mensagem da sua cota diária. Uma impressão típica envia uma ou duas.

[Crie um webhook](/webhooks), cole a configuração, e sua próxima impressão vai avisar quando terminar.
