Voltar para o blog

Notificações push do Uptime Kuma no celular: alto quando cai, silencioso quando volta

Notificações push do Uptime Kuma no celular: alto quando cai, silencioso quando volta

O Uptime Kuma é bom em perceber que algo caiu. Onde esse aviso acaba parando é outra história. A maioria das configurações envia o aviso para um grupo no Telegram, um canal no Discord ou uma pasta de e-mail, no meio de tudo mais que faz o celular vibrar durante o dia. E a mensagem de "voltou" faz exatamente o mesmo barulho que a de "caiu". Depois de algumas noites de oscilação, as pessoas silenciam o canal e param de ler.

Este guia envia os alertas do Uptime Kuma para o Pocket Alert como notificações push, com prioridades diferentes. Um monitor que cai chega como high, que passa pelo Foco no iPhone. Uma recuperação chega como low: ela fica no feed quando você olhar, e não acorda ninguém. Tudo usa o tipo de notificação Webhook que já vem no Uptime Kuma, então não há nada extra para instalar.

Tudo abaixo foi testado no Uptime Kuma 2.5.8 rodando no Docker.

O que você precisa

  • Uptime Kuma 2.x. A maior parte disso também funciona no 1.23.x; as diferenças estão anotadas no final.
  • O app do Pocket Alert no seu celular e uma conta. Crie uma conta se ainda não tiver; o plano gratuito basta para começar.
  • Uma chave de API em Chaves de API (rota 1) ou um webhook em Webhooks (rota 2).

Duas formas de conectar

A notificação Webhook do Uptime Kuma pode enviar para qualquer URL, com o JSON próprio dele ou com um corpo que você escreve. Isso dá duas rotas:

Rota 1: API do Pocket AlertRota 2: URL de webhook do Pocket Alert
URL de enviohttps://api.pocketalert.app/v1/messageshttps://p4a.me/wh/<slug>
Título da pushO que você definir, ex.: Down: WebsiteSempre Webhook <nome>
Queda alta, recuperação silenciosaSimSim, com corpo personalizado; caso contrário, um nível para tudo
Segredo guardado no Uptime KumaUma chave de API com acesso total à sua contaUma URL que só pode criar pushes por esse webhook
Registro de requisições no Pocket AlertNãoSim, no histórico de webhooks

Escolha a rota 1 se quiser títulos legíveis e o menor número de peças móveis. Escolha a rota 2 se preferir não guardar uma chave de API completa no Uptime Kuma (ele guarda as configurações de notificação, inclusive os cabeçalhos, como JSON puro no banco de dados), ou se quiser que cada requisição enviada fique registrada do lado do Pocket Alert para depuração.

Rota 1: enviar direto para a API do Pocket Alert

No Uptime Kuma, abra Settings → Notifications e clique em Set Up Notification. Preencha assim:

  • Notification Type: Webhook
  • Friendly Name: Pocket Alert
  • Post URL: https://api.pocketalert.app/v1/messages
  • HTTP Method: POST
  • Request Body: Custom Body

Cole isto no campo do corpo, substituindo kuma.example.com pelo endereço do seu Uptime Kuma:

{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}

Depois, ative Additional Headers e cole:

{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

O que o corpo faz:

  • O corpo é um template Liquid. O Uptime Kuma passa para ele msg (o texto pronto dele), monitorJSON (o monitor) e heartbeatJSON (a verificação que mudou de estado). heartbeatJSON.status é 0 para caído e 1 para no ar.
  • | json gera uma string JSON completa, com aspas. Mensagens de erro e nomes de monitores podem conter aspas e barras invertidas; com o filtro, eles não quebram a requisição. Um monitor chamado Bob's "main" site ainda gera JSON válido.
  • Down é high, Up é low. high é sensível ao tempo no iPhone e passa pelo Foco e pelo resumo agendado. low é entregue sem interromper você.
  • Marque um monitor com critical para deixá-lo mais alto. Adicione uma tag chamada critical no Uptime Kuma aos monitores mais importantes, e as quedas deles são enviadas como critical, que toca mesmo com o interruptor de silencioso e com o Não perturbe. Alertas críticos são um recurso pago; no plano gratuito, são entregues como high.
  • Certificados e mensagens de teste não têm heartbeat. Nesses casos, a push usa o texto próprio do Uptime Kuma como mensagem. O mesmo texto é usado de reserva quando a mensagem do heartbeat está vazia, como em um monitor de ping que volta a responder; a API rejeita uma push com mensagem vazia.
  • O botão abre o monitor. /dashboard/<id> é a página do monitor no Uptime Kuma. Para um aviso de certificado não há ID de monitor, e o botão abre o painel. Botões de ação são um recurso pago; no plano gratuito, a API os descarta e a push é entregue sem nenhum. Veja botões de ação para o que mais eles podem fazer.

Não pule o cabeçalho Content-Type. Quando o Uptime Kuma envia um corpo personalizado, ele marca como application/x-www-form-urlencoded, a menos que você diga o contrário. Foi isso que ele enviou no meu teste. A API do Pocket Alert só aceita JSON ou multipart, e responde a essa requisição com 400.

Clique em Test. Uma push com o título "Uptime Kuma" e o texto "Pocket Alert Testing" deve chegar em poucos segundos. Salve.

Veja o que uma queda e uma recuperação reais enviaram do Uptime Kuma 2.5.8:

{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}

Use uma chave de API separada, com o nome do Uptime Kuma, para poder revogá-la sozinha caso esse servidor seja comprometido.

Rota 2: uma URL de webhook do Pocket Alert

Aqui o Uptime Kuma envia o próprio JSON para um webhook do Pocket Alert, e um template do lado do Pocket Alert transforma isso em uma push.

Crie o webhook

O template do botão só pode ser definido pela API, então a forma mais rápida é uma única chamada. Ela cria um webhook chamado "Uptime Kuma" com um template de mensagem, um nível padrão high (1) e um botão "Open in Uptime Kuma", e depois exibe a URL de recebimento:

PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'

Se preferir clicar, crie pelo console em Webhooks: nome Uptime Kuma, Default priority High, mensagem %msg%. Você recebe as mesmas pushes, sem o botão.

Aponte o Uptime Kuma para ele

Crie uma nova notificação do tipo Webhook, cole a URL de recebimento em Post URL e defina Request Body como Preset - application/json. Não são necessários cabeçalhos: a URL é o segredo, então trate-a como uma senha. Não escolha o preset multipart; os webhooks do Pocket Alert só leem JSON.

O Uptime Kuma enviou isto do meu ambiente de teste quando um monitor caiu (resumido; o objeto monitor tem cerca de cem campos):

{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}

O template %msg% usa o msg do nível superior, porque é o único campo presente em todas as requisições. Para avisos de certificado e mensagens de teste, heartbeat e monitor são null e só msg vem preenchido. A push chega com o título "Webhook Uptime Kuma" e "[Website] [🔴 Down] timeout of 4000ms exceeded" como texto. Um placeholder cujo caminho não existe vira uma string vazia; então, em um aviso de certificado, o botão aponta para /dashboard/ e continua funcionando.

Queda alta, recuperação silenciosa nesta rota

Com o preset JSON, toda requisição recebe o nível padrão do webhook, então as recuperações chegam tão alto quanto as quedas. Para corrigir isso, mude Request Body para Custom Body e envie você mesmo um campo level. Os webhooks do Pocket Alert leem um level de nível superior no payload antes de recorrer ao padrão:

{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}

O corpo mantém os nomes de campo msg e monitor.id, então os templates de mensagem e de botão do webhook funcionam sem alterações. Os webhooks do Pocket Alert leem o corpo como JSON independentemente do Content-Type, então essa rota não precisa de cabeçalho extra.

Ative para todos os monitores

Uma notificação não faz nada até que um monitor a use. No final do formulário de notificação há duas opções:

  • Default enabled marca esta notificação em todo monitor que você criar a partir de agora.
  • Apply on all existing monitors a adiciona a todos os monitores que você já tem. Ela roda uma vez ao salvar e não é lembrada.

Ative as duas na primeira vez que salvar. Para deixar um monitor de fora, abra-o e desmarque a notificação no formulário de edição.

Avisos de expiração de certificado

O Uptime Kuma pode avisar antes de um certificado TLS expirar. Abra um monitor HTTP(s) (os monitores Keyword e JSON Query também têm essa opção) e marque Certificate Expiry Notification em Advanced. A caixa fica desabilitada enquanto Ignore TLS/SSL errors for HTTPS websites estiver ativo.

Os limites são globais, em Settings → Notifications → TLS Certificate Expiry, e o padrão é 7, 14 e 21 dias. O aviso vai para as mesmas notificações das quedas do monitor, com um texto como:

[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days

O corpo da rota 1 captura isso com msg contains "will expire" e o intitula "Expiring soon" com nível default. O Uptime Kuma envia uma vez por limite, não em cada verificação: no meu teste, o monitor foi verificado 119 vezes com um certificado a quatro dias de expirar, e exatamente um aviso foi enviado.

Impeça que um monitor instável inunde seu celular

Três configurações do monitor definem o nível de ruído que um serviço instável produz:

ConfiguraçãoO que fazSugerido
RetriesVerificações com falha marcadas como Pending antes de o monitor contar como caído. Verificações pendentes não notificam.2 ou 3
Heartbeat Retry IntervalSegundos entre as verificações enquanto estiver pendente.20 a 60
Resend Notification if Down X times consecutivelyRepete o alerta de queda depois de mais essa quantidade de verificações com falha. 0 envia uma única vez.0, ou um valor que dê 30 a 60 minutos

Com Retries em 2 no meu teste, as duas primeiras verificações com falha ficaram pendentes, e só a terceira enviou "Down". Com Resend em 3, o alerta de queda se repetiu a cada três verificações com falha adicionais, até o serviço voltar. A contagem de reenvio é em verificações, não em minutos. Com intervalo de 60 segundos, 30 significa um lembrete a cada meia hora.

Cada queda, cada volta e cada reenvio é uma mensagem. O plano gratuito permite 50 por dia, então um único monitor instável sem tentativas pode consumir tudo em uma tarde. As tentativas são a correção mais barata.

Se nada chegar

  • O teste falha com HTTP 400. Na rota 1, confira se Additional Headers inclui "Content-Type": "application/json". Sem ele, a requisição sai como dados de formulário.
  • HTTP 401. O cabeçalho Token está faltando ou a chave foi revogada. Crie uma nova em Chaves de API.
  • O teste chega, mas as quedas não. Abra o monitor e confira se a notificação está marcada. Além disso, o Uptime Kuma não notifica na primeira verificação de um monitor que está no ar, então um monitor novo fica quieto até que algo mude.
  • A rota 2 não mostra nada. Abra o histórico do webhook no console. Se a requisição estiver lá com erro, ele informa o motivo: JSON inválido ou um template que gerou uma mensagem vazia. Se nada foi registrado, o Uptime Kuma nunca chegou ao p4a.me. Você também pode enviar requisições ao testador de webhook para ver exatamente o que o Uptime Kuma envia.
  • Parece que falta uma recuperação. Pushes low são silenciosas. Confira o feed no app.

Perguntas frequentes

Qual versão do Uptime Kuma isso exige?

Foi testado na 2.5.8, a versão mais recente na data em que escrevi. A versão 1.23.x também tem o tipo Webhook com Custom Body e Additional Headers, e o template recebe as mesmas variáveis msg, monitorJSON e heartbeatJSON. Eu renderizei o corpo da rota 1 com o motor de templates que vem na 1.23.16 e obtive o mesmo JSON, mas a execução completa de ponta a ponta foi feita apenas na 2.5.8.

E se o servidor que roda o Uptime Kuma cair?

Nesse caso, nada envia o alerta. O Uptime Kuma não consegue reportar a própria queda, então rode algo fora dele que perceba o problema, como uma verificação feita de outra máquina ou um monitor hospedado. A página de monitoramento de uptime lista monitores hospedados que funcionam com webhooks do Pocket Alert.

Posso enviar monitores diferentes para celulares diferentes?

Sim, em um plano pago. Crie uma notificação por grupo com um device_id diferente no corpo (rota 1) ou um webhook diferente com o próprio dispositivo (rota 2), e marque a correta em cada monitor. O plano gratuito tem um dispositivo e um webhook, então há apenas um celular para enviar.

Isso funciona para monitores de ping, porta e DNS?

Sim. O corpo usa apenas o nome e o ID do monitor e o status e a mensagem do heartbeat, que existem em todos os tipos de monitor. Alguns tipos, entre eles o ping, deixam a mensagem vazia quando a verificação tem sucesso; nesse caso, o corpo usa como reserva o texto próprio do Uptime Kuma. O botão leva à página do monitor no Uptime Kuma, e não ao endereço verificado, então funciona mesmo quando o endereço não é uma URL.

Já uso isso para o Proxmox. Posso compartilhar uma chave de API?

Pode, mas dê ao Uptime Kuma uma chave própria, para que revogar uma não quebre a outra. O guia do Proxmox cobre alertas de backup e de disco do mesmo homelab.

Crie uma conta gratuita, cole o corpo em uma notificação Webhook e deixe a próxima queda chegar ao seu celular, enquanto a recuperação espera em silêncio no feed.

Compartilhe este artigo