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:
- 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.
- Las notificaciones urgentes pueden atravesar la Concentración. En Pocket Alert, los mensajes
highllegan como urgentes. Los niveles inferiores esperan a que termine la Concentración. - 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
criticalen 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 hace | Pocket Alert hace |
|---|---|
| Detecta el fallo y decide qué importa | Recibe la petición y comprueba tu clave de API o la URL del webhook |
| Da formato al texto o envía su propio JSON | Mapea los campos, asigna el nivel de prioridad y entrega a APNs |
| Envía el evento una vez, cuando ocurre | Envía la push a todos los dispositivos de la cuenta, o al dispositivo que indiques |
| Mantiene sus propios logs | Guarda 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. Rechazaapplication/x-www-form-urlencoded, que es lo que envíacurl -dsi omites la cabecera. Usa-H "Content-Type: application/json"con un cuerpo JSON, o-Fpara campos de formulario. titleymessageson obligatorios. Todo lo demás es opcional.- Omite
device_idpara 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:
| Nivel | Valor | En iPhone | Uso típico |
|---|---|---|---|
silent | -2 | Sin sonido, directo al Centro de notificaciones | Eventos de "resuelto", registros que podrías leer más tarde |
low | -1 | Pasiva, no enciende la pantalla | Informativa |
default | 0 | Notificación normal con sonido | Resultados rutinarios, como una copia de seguridad terminada |
high | 1 | Urgente, atraviesa la Concentración | Requiere atención pronto |
critical | 2 | Alerta crítica, suena aunque esté en silencio | Requiere 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, ocriticalpara 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
- 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.
- Prueba con la Concentración activada. Activa el modo de Concentración que uses, envía una prueba
highcon 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. - 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.
- Revisa los logs de tu origen para la petición saliente: URL, código de estado y cuerpo de la respuesta.
- 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 usagemuestra 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:
- Regístrate e instala la aplicación en tu iPhone.
- Crea una clave de API en claves de API.
- 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.