Envía los avisos de cambios de cualquier sitio o app a una bandeja de entrada compartida
Cómo integrar Nudge para recibir notificaciones
Nudge es una «bandeja de notificaciones + centro de suscripciones» abierto. Tu solo sitio necesita enviar un JSON con POST a un endpoint HTTP cada vez que ocurre algo, y tus usuarios recibirán el aviso en su propia bandeja de Nudge, junto con los avisos de los demás sitios. No hace falta montar colas de mensajes, servicios de correo ni infraestructura de push.
La integración consta de tres pasos y unos 10 minutos: sin SDK y compatible con cualquier lenguaje de backend.
Tres pasos
Consigue credenciales
Crea un «project» para tu sitio y obtén un token exclusivo.
Envía eventos
Cuando ocurra un evento, envía un JSON con POST a /api/ingest.php.
Suscripción de usuarios
Añade un botón con enlace profundo; tras iniciar sesión, el usuario se suscribe automáticamente y ve una tarjeta de bienvenida.
Paso 1 · Obtén el project y el token
Cada editor corresponde a un «project» con slug, display_name y token únicos. El token es la única credencial para enviar eventos: guárdalo solo en el servidor y nunca en código de front-end ni en un repositorio público.
php bin/create_project.php your-app "Your App Name"
# salida: slug / name / token / ingest endpoint
Paso 2 · Envía eventos a ingest
Cuando en tu sitio ocurra un cambio que «merece la pena que el usuario conozca», envía una petición JSON al endpoint ingest. Es sin estado: Nudge se encarga del almacenamiento, la deduplicación, el control de frecuencia y el reparto en la bandeja de cada suscriptor.
https://nudgealert.com/api/ingest.phpPOST · Content-Type: application/jsonPetición mínima
curl -X POST https://nudgealert.com/api/ingest.php \
-H "Content-Type: application/json" \
-d '{"token":"YOUR_TOKEN","title":"New free tier available","body":"Groq raised its free RPM to 30."}'
Petición con todos los campos
curl -X POST https://nudgealert.com/api/ingest.php \
-H "Content-Type: application/json" \
-d '{
"token": "YOUR_TOKEN",
"topic": "quota-change",
"title": "Groq free quota changed",
"body": "RPM 20 -> 10, effective today.",
"level": "high",
"dedup_key": "groq:rpm:20to10:2026-11-14"
}'
Campos de la petición y respuestas
| Campo | Obligatorio | Descripción |
|---|---|---|
token | Sí | Credencial del project, guárdala en el servidor |
title | No | Título del aviso; por defecto (no title) |
body | No | Cuerpo del mensaje, admite saltos de línea |
topic | No | Agrupación de topics (p. ej. quota-change); valor predeterminado default, los usuarios pueden suscribirse por topic |
level | No | info / warning / high / critical, por defecto info |
dedup_key | No | Clave de deduplicación: un valor repetido dentro del mismo project se guarda una sola vez y devuelve duplicated |
Respuestas
| Evento guardado | { "ok": true, "id": 12 } |
| Deduplicado | { "ok": true, "duplicated": true } |
Códigos de error
400 | invalid_json | El cuerpo de la petición no es JSON válido |
401 | missing_token | No se proporcionó el token |
403 | invalid_token | El token no es válido |
429 | rate_limited | Supera los 60 eventos por minuto y project |
500 | db_error | Error de escritura en el servidor |
Ejemplos de código
PHP
<?php
$payload = [
"token" => getenv("NUDGE_TOKEN"),
"topic" => "quota-change",
"title" => "Groq free quota changed",
"body" => "RPM 20 -> 10",
"level" => "high",
"dedup_key" => "groq:rpm:20to10:2026-11-14",
];
$ch = curl_init("https://nudgealert.com/api/ingest.php");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
// $res => ["ok" => true, "id" => 12] or ["ok" => true, "duplicated" => true]
Node.js / fetch
const res = await fetch("https://nudgealert.com/api/ingest.php", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
token: process.env.NUDGE_TOKEN,
topic: "quota-change",
title: "Groq free quota changed",
body: "RPM 20 -> 10",
level: "high",
dedup_key: "groq:rpm:20to10:2026-11-14",
}),
});
const data = await res.json();
// data => { ok: true, id: 12 } or { ok: true, duplicated: true }
Python
import os, json, urllib.request
payload = {
"token": os.environ["NUDGE_TOKEN"],
"topic": "quota-change",
"title": "Groq free quota changed",
"body": "RPM 20 -> 10",
"level": "high",
"dedup_key": "groq:rpm:20to10:2026-11-14",
}
req = urllib.request.Request(
"https://nudgealert.com/api/ingest.php",
data=json.dumps(payload).encode(),
headers={"Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(req) as r:
data = json.load(r) # {"ok": true, "id": 12}
Paso 3 · Suscríbete con un clic
Coloca un enlace profundo detrás del botón «Suscribirse a los avisos». Cuando un usuario abre Nudge e inicia sesión con su correo, queda suscrito al project correspondiente y ve una tarjeta de bienvenida que explica que los próximos avisos llegarán a esta bandeja de entrada.
https://nudgealert.com/?sub=<slug>&from=<source>| Parámetro | Descripción |
|---|---|
sub | El slug de tu project (obligatorio): decide a qué project se suscribe el usuario automáticamente |
from | Identificador de origen (opcional), se usa para el texto de origen de la tarjeta de bienvenida; los orígenes conocidos muestran un nombre amigable y un enlace de retorno |
Listo para poner en un botón / correo
<a class="btn" href="https://nudgealert.com/?sub=your-app&from=your-site"
target="_blank" rel="noopener">
Subscribe to quota alerts
</a>
Buenas prácticas
- Envía solo cuando haya cambios — Nudge sirve para «avisos de cambio», no para consultar estados. Haz POST solo cuando la cuota, el precio o el estado cambien de verdad, para no molestar.
- Aprovecha dedup_key — Genera una clave estable a partir de «objeto + cambio» (p. ej. groq:rpm:20to10) para que un cron repetido no inunde al usuario.
- Elige bien el level — info para lo normal, warning para lo que requiere atención, high para lo importante, critical para lo urgente: el usuario distingue la prioridad de un vistazo.
- Agrupa por topic — Separa los distintos tipos de evento en un topic distinto para que el usuario solo se suscriba a los temas que le importan.
- Protege el token — Guarda el token solo en variables de entorno o configuración del servidor; si se filtra, pide al administrador que lo reinicie de inmediato.
- Llamadas desde el servidor — Envía siempre desde el backend: nunca expongas el token al navegador ni a los clientes.
Preguntas frecuentes
¿Necesito un SDK o una cuenta?
No. Al editor solo le bastan un token y una petición HTTP POST; los usuarios se suscriben entrando en Nudge con su correo, sin contraseña.
¿Los eventos se envían a todos?
Solo a los usuarios suscritos a tu project (y al topic correspondiente). Los demás no pueden verlos.
¿Hay límite de frecuencia?
Sí, 60 eventos por minuto como máximo y project (429 rate_limited). Para eventos en lote, conviene agruparlos o escalonarlos.
¿Se pueden reenviar a mi propio webhook?
Sí. Al suscribirse, el usuario puede indicar un webhook de reenvío; Nudge redistribuye los eventos a WeCom / Slack / Telegram / endpoints personalizados.
¿La entrega es en tiempo real?
Los eventos son visibles para el usuario en cuanto se guardan (bandeja de entrada). Canales como las notificaciones del navegador o el correo dependen de la configuración del usuario y de las funciones que se abran más adelante.
¿Todo listo para integrar?
Envía la información de tu sitio al administrador para obtener un token, copia uno de los ejemplos de arriba, cambia dos líneas y tu primer aviso llega a Nudge.
Abrir la bandeja de Nudge →