Alertas y webhooks
La página Alerts (owners y admins) decide quién recibe un email sobre los eventos operativos, y envía los mismos eventos a tus propios endpoints como webhooks firmados: para avisarle a alguien de guardia, publicar en un chat o abrir un ticket en tu gestor.
Eventos
| Evento | Cuándo | Email por defecto a | Campos de data |
|---|---|---|---|
backup.failed | Un backup programado o manual no se completó, o una restauración a un punto en el tiempo no encontró nada que copiar | Owners, admins | backup_id, database, backup_kind, finished_at |
backup.succeeded | Un backup terminó (es frecuente, así que no se envía por email salvo que lo actives) | nadie | backup_id, database, backup_kind, bytes, finished_at |
restore.finished | Una restauración en una base de datos nueva terminó bien o falló | Owners, admins | restore_id, backup_id, status, database, source_database, finished_at |
export.ready | Una exportación de una base de datos terminó y se puede descargar. Quien la pidió también recibe su propio email, una vez | Owners, admins | export_id, database, expires_at |
engine.failing | El motor de la base de datos se detuvo inesperadamente 3 o más veces en una hora (como máximo una alerta cada 6 horas) | Owners, admins | failures_last_hour, out_of_memory |
engine.out_of_memory | Una consulta o carga de trabajo usó más memoria de la que permite el plan y el motor se reinició (como máximo una alerta cada 6 horas) | Owners, admins | failures_last_hour, plan |
usage.threshold | Se usó el 80% o el 100% de una cuota (almacenamiento, escrituras, lecturas) en este periodo | Owners, admins | metric, threshold, period_end |
spend_cap.reached | El spend cap (o la cuota de Free) detuvo las escrituras o las lecturas hasta que se reinicie el periodo | Owners, admins | blocked, metric, period_end |
org.paused | Una organización Free se pausó después de 7 días sin actividad | Owners | paused_at |
org.suspended | NamiDB suspendió la organización | Owners, admins | suspended_at, reason |
api_key.expiring | Una API key vence en 7 días o en 1 día | Owners, admins | window, keys |
Para cada evento eliges qué roles reciben el email (owners, admins, members), o nadie.
Webhooks
Agrega hasta 10 endpoints por organización. Cada uno tiene una URL https
en una dirección pública y recibe todos los eventos o una lista elegida. Crear,
cambiar, rotar o eliminar un webhook pide tu segundo factor cuando tienes uno,
y queda en el registro de auditoría.
Payload
Cada entrega es un POST con un cuerpo JSON:
{ "id": "evt_…", "type": "backup.failed", "created_at": "2026-11-02T09:30:12.481Z", "org": { "id": "5b0c…", "slug": "acme" }, "data": { "backup_id": "0b4c…", "database": "movies", "backup_kind": "scheduled", "finished_at": "2026-11-02T09:30:11Z" }}y estas cabeceras:
| Cabecera | Valor |
|---|---|
NamiDB-Event | El tipo de evento, por ejemplo backup.failed |
NamiDB-Delivery | El id de la entrega: es el mismo en todos los reintentos, así que úsalo para deduplicar |
NamiDB-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
User-Agent | NamiDB-Webhooks/1.0 (+https://namidb.com) |
Send test entrega un evento webhook.test de inmediato (nunca se
reintenta).
Verificar la firma
Cada endpoint tiene un secreto de firma (whsec_…), que se muestra una sola
vez cuando lo creas o lo rotas. La firma es HMAC-SHA256(secret, "<t>.<raw body>")
en hexadecimal. Calcúlala sobre el cuerpo crudo de la petición, compara en
tiempo constante y rechaza las marcas de tiempo con más de 5 minutos de
antigüedad.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyNamiDB(secret: string, rawBody: string, header: string, toleranceS = 300): boolean { const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=', 2))); const t = Number(parts.t); if (!Number.isInteger(t) || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceS) return false; const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')); const given = Buffer.from(parts.v1); return expected.length === given.length && timingSafeEqual(expected, given);}import hashlib, hmac, time
def verify_namidb(secret: str, raw_body: bytes, header: str, tolerance_s: int = 300) -> bool: parts = dict(p.strip().split("=", 1) for p in header.split(",")) try: t = int(parts["t"]) except (KeyError, ValueError): return False if abs(time.time() - t) > tolerance_s or "v1" not in parts: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, parts["v1"])Rotate secret emite un secreto nuevo de inmediato; actualiza tu receptor justo después de rotarlo.
Respuestas y reintentos
- Responde con cualquier estado
2xxen menos de 10 segundos. Las redirecciones no se siguen, y solo se leen los primeros 4 KB de tu respuesta. - Una entrega fallida se reintenta después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas (8 intentos en total).
- Las entregas pueden llegar más de una vez o fuera de orden: deduplica por
NamiDB-Delivery(o por eliddel payload) y usacreated_at. - Un endpoint cuyas últimas 5 entregas fallaron en todos los reintentos se desactiva, con el motivo visible en la página. Vuelve a activarlo cuando esté corregido.
La página muestra el log de entregas (estado, código de respuesta, hora) y los eventos recientes. Las entregas y los eventos se conservan 30 días.