Voltar para o blog

Notificações push confiáveis no iPhone a partir de uma stack auto-hospedada

Notificações push confiáveis no iPhone a partir de uma stack auto-hospedada

Seu alerta do Grafana dispara às 3 da manhã. Os logs do servidor mostram que a chamada do webhook deu certo. Seu iPhone continua em silêncio. Monitoramento auto-hospedado é bom para detectar falhas. Fazer a mensagem chegar ao celular é onde a maioria das configurações de homelab quebra.

Este guia explica por que as notificações push no iPhone a partir de uma stack auto-hospedada são difíceis, como é um caminho confiável e como conectar Grafana, Uptime Kuma, n8n, tarefas cron e scripts de shell. O primeiro alerta funcionando leva cerca de cinco minutos.

Por que o push no iOS quebra em configurações auto-hospedadas

Só o APNs consegue chegar a um iPhone

Toda notificação push para um iPhone passa pelo Apple Push Notification service (APNs). Seu servidor não consegue abrir uma conexão com o celular e enviar dados diretamente. O celular mantém uma conexão de longa duração com a Apple. Seu servidor envia cada mensagem ao APNs por HTTP/2, autenticado com uma chave da sua conta de desenvolvedor Apple. Em seguida, o APNs entrega a mensagem pela conexão já existente do celular.

Isso significa que sua stack precisa de um remetente capaz de falar com o APNs no meio do caminho. O celular nunca consulta seu servidor, então um endpoint de webhook comum na sua LAN não tem para onde entregar. Para entender melhor o caminho de entrega, veja como as notificações push chegam a um iPhone.

Rodar seu próprio remetente dá mais trabalho do que parece

Você pode falar com o APNs diretamente. Precisa de uma chave de assinatura (um arquivo .p8 para autenticação por token, que não expira todo ano, ou um certificado de cliente TLS por aplicativo, que expira), de um aplicativo registrado, de um jeito de armazenar os tokens dos dispositivos e de código que trate erros e novas tentativas do APNs. Também precisa de um aplicativo iOS que registre o dispositivo e exiba o alerta. Cada peça é gerenciável isoladamente. O custo real é mantê-las funcionando através da rotação de chaves e das mudanças de política da Apple.

A maioria dos auto-hospedados precisa do resultado, não da encanação. Um serviço hospedado que já cuida do lado do APNs deixa sua stack simples: uma requisição HTTP por alerta.

Foco, silenciar e níveis de interrupção

O iOS decide com que intensidade entregar cada notificação com base no nível de interrupção, nos seus modos de Foco e nas configurações do aplicativo. Três coisas importam para alertas:

  1. As notificações precisam estar permitidas para o aplicativo. Verifique isso primeiro nos Ajustes do iOS. Um aplicativo silenciado nunca vai exibir seu alerta, não importa como o servidor se comporte.
  2. Notificações urgentes conseguem furar o Foco. No Pocket Alert, mensagens high chegam como urgentes. Níveis mais baixos esperam o Foco terminar.
  3. Alertas críticos ignoram a chave de silêncio e o Não perturbe. Eles precisam de uma permissão especial que a Apple concede após análise. O Pocket Alert tem essa permissão: mensagens critical em planos pagos tocam um som mesmo com o celular silenciado, desde que você tenha permitido Alertas Críticos para o aplicativo. Se você desativou essa permissão, elas chegam como urgentes.

A seção de prioridade abaixo explica como definir o nível.

Como é uma configuração confiável

Sua stack detecta um problema e envia uma requisição HTTP. Um serviço hospedado assume a partir daí:

Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)

A divisão de tarefas fica assim:

Sua stack fazO Pocket Alert faz
Detecta a falha e decide o que importaRecebe a requisição e verifica sua chave de API ou URL do webhook
Formata o texto ou envia seu próprio JSONMapeia os campos, define o nível de prioridade e entrega ao APNs
Envia o evento uma vez, quando ele aconteceEnvia o push para todos os dispositivos da conta ou para o dispositivo que você indicar
Mantém os próprios logsMantém o histórico de mensagens e um log de requisições para cada webhook, para você ver o que chegou e o que falhou

Envie seu primeiro alerta com curl

Crie sua conta em pocketalert.app/signup, abra chaves de API e clique em Create New Key. A chave é mostrada apenas uma vez, então copie-a para um lugar seguro.

Guarde-a em uma variável de ambiente e envie uma mensagem:

export PA_KEY="YOUR_API_KEY"

curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: $PA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup finished",
    "message": "nightly-backup on nas01 completed in 14m",
    "level": "high"
  }'

Uma chamada bem-sucedida retorna JSON com tid, title, message, application, device e created_at. Guarde o tid se quiser associar um push a uma linha de log depois.

Três coisas costumam dar problema:

  • Defina o Content-Type. A API aceita JSON ou multipart/form-data. Ela rejeita application/x-www-form-urlencoded, que é o que o curl -d envia quando você não passa o cabeçalho. Use -H "Content-Type: application/json" com um corpo JSON, ou -F para campos de formulário.
  • title e message são obrigatórios. Todo o resto é opcional.
  • Omita device_id para alcançar todos os dispositivos da conta. Inclua-o quando tiver mais de um celular e quiser um específico.

Envie alertas pela linha de comando

A CLI do Pocket Alert é a forma mais rápida de integrar alertas aos scripts existentes. Instale com o script de shell, Homebrew ou Go:

curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest

Execute pocketalert auth uma vez e cole sua chave. A chave fica armazenada em ~/.pocketalert/config.json, legível apenas por você. Em servidores, containers e CI, defina POCKETALERT_API_KEY.

Envie uma mensagem:

pocketalert send "Deploy finished" "v2.4.0 is live" --level high

Envie a saída de um comando direto para um alerta:

df -h | pocketalert send "Disk report" --level default

Ou envolva um comando com exec. Ele executa o comando normalmente e então envia um push com o código de saída, a duração e as últimas linhas da saída, repassando o código de saída:

pocketalert exec -t "Database dump" -- ./dump.sh

Use -q para imprimir apenas o ID da mensagem, o que é útil em scripts. Adicione --json a qualquer comando para obter saída legível por máquina.

Webhooks com mapeamento de campos

Quando sua fonte já envia JSON, como Grafana, Uptime Kuma ou um serviço próprio, você não precisa escrever um remetente. Crie um webhook no console em Webhooks, e o Pocket Alert gera uma URL de recebimento como https://p4a.me/wh/1234abcd. O slug não é adivinhável, e cada URL está vinculada a um webhook e a um aplicativo. Aponte sua fonte para essa URL com POST.

O push chega com o título "Webhook" mais o nome do webhook, então dê a ele o nome da fonte, por exemplo Grafana. O template da mensagem extrai valores do JSON recebido com caminhos GJSON:

  • %object.field% para campos aninhados
  • %items.0.name% para itens de array
  • %users.#% para uma contagem
  • * como template inteiro envia o corpo completo

Por exemplo, um template para um payload recebido como este:

{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}

poderia ser:

[%state%] %service%: %check%
%detail%

Um placeholder cujo caminho não existe é renderizado como string vazia, então um erro de digitação aparece como um espaço vazio no texto, não como um erro.

Antes de escrever um template, capture o payload real. Abra o testador de webhook, copie a URL de teste e aponte sua fonte para ela. O testador mostra o método, os cabeçalhos e o corpo, para que você escreva os caminhos com base no que sua fonte realmente envia. Não envie segredos de produção para uma URL de teste pública. Qualquer pessoa que conheça a URL pode ler o que chega nela.

A prioridade funciona de duas formas. Defina um nível padrão no webhook ou inclua um campo level no nível superior do payload, que substitui o padrão. Os valores válidos são silent, low, default, high e critical, ou os números de -2 a 2. Um level inválido é ignorado, e o padrão do webhook é aplicado.

Integrações

Alertas do Grafana

No console, crie um webhook chamado Grafana com este template de mensagem:

[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%

Copie a URL de recebimento. No Grafana, vá em Alerting → Contact points → Add contact point, escolha a integração Webhook e defina:

Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST

Vincule o contact point a uma notification policy para que os alertas correspondentes sejam roteados para ele e, em seguida, pressione o botão Test do contact point. Um alerta disparado chamado HighCPU com o label severity="critical" aparece como [firing] HighCPU (critical). Quando ele se normaliza, o mesmo push chega com resolved entre colchetes.

Três observações. A parte severity fica vazia a menos que suas regras definam esse label. O template lê apenas o primeiro alerta de um grupo (alerts.0), então, se uma notificação agrupar vários alertas, você verá apenas o resumo do primeiro. E o período pending de cada regra (por exemplo, 5 minutos) é a forma mais barata de impedir que uma métrica instável acorde seu celular a cada minuto. O guia do Grafana cobre mais campos.

Uptime Kuma

O Uptime Kuma envia um webhook a cada mudança de status. Adicione uma notificação do tipo Webhook, defina Post URL como sua URL de recebimento e mantenha o preset JSON como corpo da requisição.

No Pocket Alert, use %msg% como template. msg é o único campo presente em toda requisição que o Uptime Kuma envia, incluindo avisos de certificado e mensagens de teste, e já vem legível, como "[Website] [🔴 Down] timeout of 4000ms exceeded". Defina o nível padrão do webhook como high.

Com o corpo predefinido, as recuperações chegam tão altas quanto as quedas, porque o Uptime Kuma não adiciona um campo level por conta própria. O guia do Uptime Kuma mostra um corpo personalizado que envia high para quedas e low para recuperações.

n8n

Em um workflow do n8n, adicione um nó HTTP Request depois da etapa que detecta o problema:

  • Method: POST
  • URL: https://api.pocketalert.app/v1/messages
  • Authentication: Generic Credential Type, depois Header Auth. Nome Token, valor sua chave de API.
  • Send Body: ativado, Body Content Type JSON, Specify Body Using JSON, com uma expressão que monta o objeto inteiro:
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}

JSON.stringify escapa aspas e quebras de linha nos valores, o que não acontece com "{{ $json.detail }}" simples dentro de uma string JSON. Para falhas em todos os workflows, configure um workflow de erro que comece com um Error Trigger: o nome do workflow com falha está em $json.workflow.name e o erro em $json.execution.error.message. O guia do n8n tem um workflow pronto para importar.

Verificações agendadas e recorrentes

Tarefas cron falham em silêncio, que é o pior momento para perder um alerta. Coloque o alerta na própria tarefa:

POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh

O cron não carrega o perfil do seu shell, então as duas linhas no topo dão à tarefa a chave e um PATH que inclui a CLI. Uma execução bem-sucedida chega como "✓ Nightly backup" no nível padrão. Uma falha chega como "✗ Nightly backup (exit 1)" em high, com as últimas linhas da saída na mensagem. Adicione --on failure se você quiser ser avisado apenas sobre falhas.

O exec avisa quando uma tarefa falha, não quando ela nunca é executada. Para isso, combine-o com um dead man's switch, como no guia de monitoramento de tarefas cron.

Se não tiver certeza sobre um agendamento, cole-o na ferramenta gratuita de expressões cron. Ela decodifica cada campo em linguagem simples e lista os próximos horários de execução. Os horários usam o fuso horário do seu navegador, que pode ser diferente do fuso do servidor.

Níveis de prioridade e alertas críticos

Há cinco níveis disponíveis, do mais silencioso ao mais alto:

NívelValorNo iPhoneUso típico
silent-2Sem som, direto para a Central de NotificaçõesEventos de "resolvido", logs que você pode ler depois
low-1Passiva, não acende a telaInformativo
default0Notificação normal com somResultados de rotina, como um backup concluído
high1Urgente, fura o FocoPrecisa de atenção em breve
critical2Alerta Crítico, toca mesmo silenciadoPrecisa de atenção agora. Apenas planos pagos

No plano gratuito, uma mensagem critical é entregue como high. Ela ainda chega imediatamente como urgente, mas respeita a chave de silêncio.

Um mapeamento razoável para um alerta disparado e sua resolução:

  • disparado: high, ou critical para as poucas coisas que valem acordar
  • resolvido: silent

Defina isso com o nível padrão do webhook ou com um campo level no payload, quando sua fonte puder enviá-lo.

Checklist: garanta que seu alerta chegue

  1. Permita notificações para o aplicativo Pocket Alert nos Ajustes do iOS, incluindo Notificações Urgentes e, em um plano pago, Alertas Críticos.
  2. Teste com o Foco ativado. Ligue o modo de Foco que você usa, envie um teste high com o comando curl acima e confirme que ele passa. Se não passar, verifique as configurações de notificação do aplicativo para esse Foco.
  3. Confirme que a chamada chegou ao Pocket Alert. Mensagens de API aparecem no histórico de mensagens do aplicativo e do console web. Chamadas de webhook, inclusive as rejeitadas, aparecem no log de requisições daquele webhook. Se a chamada estiver lá, o problema está no celular. Se não estiver, o problema está na sua fonte.
  4. Verifique os logs da sua fonte para a requisição de saída: URL, código de status e corpo da resposta.
  5. Acompanhe o limite diário. O plano gratuito permite 50 notificações por dia. Uma verificação instável pode consumir isso em uma hora, então ajuste os limites e os períodos pending antes de escalar. pocketalert usage mostra quantas você ainda tem hoje.

Se um alerta ainda não chegar, siga os passos em ordem: log da fonte, depois o histórico do Pocket Alert, depois as configurações de nível e dispositivo. Essa ordem isola rapidamente o ponto de falha.

FAQ

Posso enviar notificações push para um iPhone sem uma configuração de desenvolvedor Apple própria?
Sim. Um serviço hospedado que já se conecta ao APNs cuida do lado da Apple. Você envia uma requisição HTTP com sua chave de API, e o serviço a entrega ao aplicativo do iPhone. Rodar seu próprio remetente exige chaves de assinatura, registro de aplicativo e um aplicativo iOS próprio.

Por que meus alertas auto-hospedados chegam atrasados ou não chegam?
Geralmente por uma destas três razões: as notificações não estão permitidas para o aplicativo, o Foco ativo retém o alerta pelo seu nível, ou a requisição nunca chegou ao serviço. Verifique primeiro o histórico de mensagens ou o log do webhook para ver qual delas se aplica.

Os alertas vão passar quando o Foco estiver ativado?
Mensagens high chegam como urgentes, que podem furar o Foco depois que as notificações forem permitidas. Mensagens critical em planos pagos vão além e tocam mesmo com o celular silenciado. Níveis mais baixos esperam. Teste sua própria configuração de Foco antes de depender dela.

Existe um plano gratuito?
Sim. O plano gratuito inclui 50 notificações por dia, 1 dispositivo, 1 aplicativo e 1 webhook. Mensagens críticas são entregues com prioridade alta no plano gratuito.

Próximos passos

Você pode ter seu primeiro alerta no iPhone em cerca de cinco minutos:

  1. Crie sua conta e instale o aplicativo no seu iPhone.
  2. Crie uma chave de API em chaves de API.
  3. Execute o comando curl deste guia.

Quando isso funcionar, conecte uma fonte real: um contact point do Grafana, uma notificação do Uptime Kuma ou uma tarefa cron. Para mais fontes de homelab, veja alertas para homelab e o guia do Proxmox. Para outras integrações, veja notificações por webhook e alertas do Grafana. Se você está comparando opções, a página de alternativas mostra as diferenças.

Compartilhe este artigo