Volver al blog

Notificaciones push fiables en iPhone desde un stack autoalojado

Notificaciones push fiables en iPhone desde un stack autoalojado

Tu alerta de Grafana se dispara a las 3 a. m. Los logs del servidor indican que la llamada al webhook salió bien. Tu iPhone sigue en silencio. La monitorización autoalojada es buena detectando fallos. Hacer que el mensaje llegue al teléfono es donde most configuraciones de homelab fallan.

Esta guía explica por qué las notificaciones push en iPhone desde un stack autoalojado son difíciles, cómo es una ruta fiable y cómo conectar Grafana, Uptime Kuma, n8n, tareas cron y scripts de shell. La primera alerta funcionando tarda unos cinco minutos.

Por qué fallan las notificaciones push en iOS con sistemas autoalojados

Solo APNs puede llegar a un iPhone

Cada notificación push a un iPhone pasa por Apple Push Notification service (APNs). Tu servidor no puede abrir una conexión con el teléfono ni enviarle datos directamente. El teléfono mantiene una conexión persistente con Apple. Tu servidor envía cada mensaje a APNs por HTTP/2, autenticado con una clave de tu cuenta de desarrollador de Apple. APNs lo entrega después por la conexión que el teléfono ya tiene abierta.

Eso significa que tu stack necesita un emisor capaz de hablar con APNs en medio. El teléfono nunca consulta a tu servidor, así que un endpoint de webhook simple en tu LAN no tiene a dónde entregar nada. Para entender mejor la ruta de entrega, consulta cómo llegan las notificaciones push a un iPhone.

Enviar tú mismo las notificaciones da más trabajo de lo que parece

Puedes comunicarte con APNs por tu cuenta. Necesitas una clave de firma (un archivo .p8 para la autenticación por token, que no caduca cada año, o un certificado de cliente TLS por aplicación, que sí caduca), una aplicación registrada, una forma de guardar los tokens de los dispositivos y código que gestione los errores y los reintentos de APNs. También necesitas una aplicación de iOS que registre el dispositivo y muestre la alerta. Cada pieza es manejable por separado. Lo costoso de verdad es mantenerlas todas funcionando a través de la rotación de claves y los cambios en las políticas de Apple.

La mayoría de quienes autoalojan quieren el resultado, no la fontanería. Un servicio alojado que ya gestiona la parte de APNs permite que tu stack siga siendo sencillo: una petición HTTP por alerta.

Concentración, silencio y niveles de interrupción

iOS decide con qué intensidad entrega cada notificación según su nivel de interrupción, tus modos de Concentración y la configuración de la aplicación. Tres cosas importan para las alertas:

  1. Las notificaciones deben estar permitidas para la aplicación. Compruébalo primero en Ajustes de iOS. Una aplicación silenciada nunca mostrará tu alerta, da igual cómo se comporte el servidor.
  2. Las notificaciones urgentes pueden atravesar la Concentración. En Pocket Alert, los mensajes high llegan como urgentes. Los niveles inferiores esperan a que termine la Concentración.
  3. Las alertas críticas ignoran el interruptor de silencio y No molestar. Necesitan un permiso especial que Apple concede tras revisión. Pocket Alert lo tiene: los mensajes critical en planes de pago suenan aunque el teléfono esté en silencio, siempre que hayas permitido las Alertas críticas para la aplicación. Si desactivaste ese permiso, llegan como urgentes.

La sección de prioridades más abajo explica cómo establecer el nivel.

Cómo es una configuración fiable

Tu stack detecta un problema y envía una petición HTTP. A partir de ahí, un servicio alojado se encarga:

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

El reparto del trabajo es este:

Tu stack hacePocket Alert hace
Detecta el fallo y decide qué importaRecibe la petición y comprueba tu clave de API o la URL del webhook
Da formato al texto o envía su propio JSONMapea los campos, asigna el nivel de prioridad y entrega a APNs
Envía el evento una vez, cuando ocurreEnvía la push a todos los dispositivos de la cuenta, o al dispositivo que indiques
Mantiene sus propios logsGuarda el historial de mensajes y un registro de peticiones por cada webhook, para que veas qué llegó y qué falló

Envía tu primera alerta con curl

Regístrate en pocketalert.app/signup, abre claves de API y haz clic en Create New Key. La clave se muestra una sola vez, así que cópiala en un lugar seguro.

Guárdala en una variable de entorno y envía un mensaje:

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"
  }'

Una llamada correcta devuelve JSON con tid, title, message, application, device y created_at. Guarda el tid si quieres relacionar después una push con una línea de log.

Tres cosas hacen tropezar a la gente:

  • Define el Content-Type. La API acepta JSON o multipart/form-data. Rechaza application/x-www-form-urlencoded, que es lo que envía curl -d si omites la cabecera. Usa -H "Content-Type: application/json" con un cuerpo JSON, o -F para campos de formulario.
  • title y message son obligatorios. Todo lo demás es opcional.
  • Omite device_id para llegar a todos los dispositivos de la cuenta. Añádelo cuando tengas más de un teléfono y quieras uno concreto.

Envía alertas desde la línea de comandos

La CLI de Pocket Alert es la forma más rápida de integrar alertas en scripts existentes. Instálala con el script de shell, Homebrew o 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

Ejecuta pocketalert auth una vez y pega tu clave. La clave se guarda en ~/.pocketalert/config.json, legible solo por ti. En servidores, contenedores y CI, define POCKETALERT_API_KEY en su lugar.

Envía un mensaje:

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

Envía directamente la salida de un comando como alerta:

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

O envuelve un comando con exec. Ejecuta el comando como de costumbre, luego envía una sola push con el código de salida, la duración y las últimas líneas de salida, y devuelve el mismo código de salida:

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

Usa -q para imprimir solo el ID del mensaje, útil para scripts. Añade --json a cualquier comando para obtener una salida legible por máquinas.

Webhooks con mapeo de campos

Cuando tu origen ya envía JSON, como Grafana, Uptime Kuma o un servicio propio, no necesitas escribir un emisor. Crea un webhook en la consola, en Webhooks, y Pocket Alert te dará una URL de recepción como https://p4a.me/wh/1234abcd. El slug no es adivinable, y cada URL está asociada a un webhook y a una aplicación. Apunta tu origen a esa URL con POST.

La push llega con el título "Webhook" más el nombre del webhook, así que ponle el nombre del origen, por ejemplo Grafana. La plantilla del mensaje toma valores del JSON entrante con rutas GJSON:

  • %object.field% para campos anidados
  • %items.0.name% para elementos de un array
  • %users.#% para un recuento
  • * como plantilla completa envía el cuerpo entero

Por ejemplo, una plantilla para un payload entrante como este:

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

podría ser:

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

Un marcador cuya ruta no existe se muestra como cadena vacía, así que un error tipográfico aparece como un hueco en el texto, no como un error.

Antes de escribir una plantilla, captura el payload real. Abre el probador de webhooks, copia la URL de prueba y apunta tu origen a ella. El probador muestra el método, las cabeceras y el cuerpo, para que escribas las rutas según lo que tu origen realmente envía. No envíes secretos de producción a una URL de prueba pública. Cualquiera que conozca la URL puede leer lo que llega ahí.

La prioridad funciona de dos maneras. Establece un nivel por defecto en el webhook, o incluye un campo level en el nivel superior del payload, que sobrescribe el valor por defecto. Los valores válidos son silent, low, default, high y critical, o los números -2 a 2. Un level no válido se ignora y se aplica el valor por defecto del webhook.

Integraciones

Alertas de Grafana

En la consola, crea un webhook llamado Grafana con esta plantilla de mensaje:

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

Copia su URL de recepción. En Grafana, ve a Alerting → Contact points → Add contact point, elige la integración Webhook y configura:

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

Asocia el contact point a una notification policy para que las alertas coincidentes se enruten hacia él, y luego pulsa el botón Test del contact point. Una alerta activa llamada HighCPU con la etiqueta severity="critical" aparece como [firing] HighCPU (critical). Cuando se resuelve, llega la misma push con resolved entre corchetes.

Tres notas. La parte severity queda vacía a menos que tus reglas definan esa etiqueta. La plantilla solo lee la primera alerta de un grupo (alerts.0), así que si una notificación agrupa varias alertas, solo ves el resumen de la primera. Y el periodo pending de cada regla (por ejemplo, 5 minutos) es la forma más económica de evitar que una métrica intermitente despierte tu teléfono cada minuto. La guía de Grafana cubre más campos.

Uptime Kuma

Uptime Kuma envía un webhook en cada cambio de estado. Añade una notificación de tipo Webhook, define Post URL con tu URL de recepción y deja el preset JSON como cuerpo de la petición.

En Pocket Alert, usa %msg% como plantilla. msg es el único campo presente en cada petición que envía Uptime Kuma, incluidas las advertencias de certificados y los mensajes de prueba, y ya se lee como "[Website] [🔴 Down] timeout of 4000ms exceeded". Establece el nivel por defecto del webhook en high.

Con el cuerpo predefinido, las recuperaciones llegan igual de fuertes que las caídas, porque Uptime Kuma no añade por sí mismo un campo level. La guía de Uptime Kuma muestra un cuerpo personalizado que envía high para las caídas y low para las recuperaciones.

n8n

En un workflow de n8n, añade un nodo HTTP Request después del paso que detecta el problema:

  • Method: POST
  • URL: https://api.pocketalert.app/v1/messages
  • Authentication: Generic Credential Type, luego Header Auth. Nombre Token, valor tu clave de API.
  • Send Body: activado, Body Content Type JSON, Specify Body Using JSON, con una expresión que construya el objeto completo:
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}

JSON.stringify escapa las comillas y los saltos de línea de los valores, algo que no hace "{{ $json.detail }}" simple dentro de una cadena JSON. Para fallos en todos los workflows, configura un error workflow que empiece con un Error Trigger: el nombre del workflow fallido está en $json.workflow.name y el error en $json.execution.error.message. La guía de n8n incluye un workflow listo para importar.

Comprobaciones programadas y recurrentes

Las tareas cron fallan en silencio, que es el peor momento para perder una alerta. Pon la alerta en la propia tarea:

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

Cron no carga tu perfil de shell, así que las dos líneas de arriba dan a la tarea la clave y un PATH que incluye la CLI. Una ejecución correcta llega como "✓ Nightly backup" con el nivel por defecto. Una fallida llega como "✗ Nightly backup (exit 1)" con high, y con las últimas líneas de salida en el mensaje. Añade --on failure si solo quieres enterarte de los fallos.

exec te avisa cuando una tarea falla, no cuando nunca se ejecuta. Para eso, combínalo con un dead man's switch, como en la guía de monitorización de tareas cron.

Si no estás seguro de una programación, pégala en la herramienta gratuita de expresiones cron. Decodifica cada campo en lenguaje natural y lista las próximas ejecuciones. Las horas de próxima ejecución usan la zona horaria de tu navegador, que puede diferir de la del servidor.

Niveles de prioridad y alertas críticas

Hay cinco niveles disponibles, de menor a mayor intensidad:

NivelValorEn iPhoneUso típico
silent-2Sin sonido, directo al Centro de notificacionesEventos de "resuelto", registros que podrías leer más tarde
low-1Pasiva, no enciende la pantallaInformativa
default0Notificación normal con sonidoResultados rutinarios, como una copia de seguridad terminada
high1Urgente, atraviesa la ConcentraciónRequiere atención pronto
critical2Alerta crítica, suena aunque esté en silencioRequiere atención ahora. Solo planes de pago

En el plan gratuito, un mensaje critical se entrega como high. Sigue llegando de inmediato como urgente, pero respeta el interruptor de silencio.

Una asignación razonable para una alerta activa y su resolución:

  • activa: high, o critical para las pocas cosas que merecen despertarte
  • resuelta: silent

Configúralo con el nivel por defecto del webhook, o con un campo level en el payload cuando tu origen pueda enviarlo.

Lista de comprobación: asegúrate de que tu alerta llega

  1. Permite las notificaciones de la aplicación Pocket Alert en Ajustes de iOS, incluidas las Notificaciones urgentes y, en un plan de pago, las Alertas críticas.
  2. Prueba con la Concentración activada. Activa el modo de Concentración que uses, envía una prueba high con el comando curl de arriba y confirma que llega. Si no llega, revisa la configuración de notificaciones de la aplicación para esa Concentración.
  3. Confirma que la llamada llegó a Pocket Alert. Los mensajes de la API aparecen en el historial de mensajes de la aplicación y de la consola web. Las llamadas a webhooks, incluidas las rechazadas, aparecen en el registro de peticiones de ese webhook. Si la llamada está ahí, el problema está en el teléfono. Si no está, el problema está en tu origen.
  4. Revisa los logs de tu origen para la petición saliente: URL, código de estado y cuerpo de la respuesta.
  5. Vigila el límite diario. El plan gratuito permite 50 notificaciones al día. Una comprobación intermitente puede agotarlo en una hora, así que ajusta los umbrales y los periodos pending antes de escalar. pocketalert usage muestra cuántas te quedan hoy.

Si una alerta sigue sin llegar, revisa los pasos en orden: log del origen, luego historial de Pocket Alert, y después niveles y configuración del dispositivo. Este orden aísla rápidamente el salto que falla.

Preguntas frecuentes

¿Puedo enviar notificaciones push a un iPhone sin tener una configuración propia de desarrollador de Apple?
Sí. Un servicio alojado que ya se conecta a APNs gestiona la parte de Apple. Envías una petición HTTP con tu clave de API, y el servicio la entrega a su aplicación para iPhone. Enviar tú mismo requiere claves de firma, un registro de aplicación y una aplicación de iOS propia.

¿Por qué mis alertas autoalojadas llegan tarde o no llegan?
Normalmente se debe a una de tres cosas: las notificaciones no están permitidas para la aplicación, la Concentración activa retiene la alerta según su nivel, o la petición nunca llegó al servicio. Revisa primero el historial de mensajes o el log del webhook para ver cuál aplica.

¿Las alertas llegan cuando la Concentración está activada?
Los mensajes high llegan como urgentes, que pueden atravesar la Concentración una vez permitidas las notificaciones. Los mensajes critical en planes de pago llegan más lejos y suenan aunque el teléfono esté en silencio. Los niveles inferiores esperan. Prueba tu propia configuración de Concentración antes de depender de ella.

¿Hay un plan gratuito?
Sí. El plan gratuito incluye 50 notificaciones al día, 1 dispositivo, 1 aplicación y 1 webhook. Los mensajes críticos se entregan con prioridad alta en el plan gratuito.

Próximos pasos

Puedes tener tu primera alerta en el iPhone en unos cinco minutos:

  1. Regístrate e instala la aplicación en tu iPhone.
  2. Crea una clave de API en claves de API.
  3. Ejecuta el comando curl de esta guía.

Cuando eso funcione, conecta una fuente real: un contact point de Grafana, una notificación de Uptime Kuma o una tarea cron. Para más fuentes de homelab, consulta alertas para homelab y la guía de Proxmox. Para otras integraciones, consulta notificaciones por webhook y alertas de Grafana. Si estás comparando opciones, la página de alternativas expone las diferencias.

Comparte este artículo