Saltearse al contenido

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

EventoCuándoEmail por defecto aCampos de data
backup.failedUn backup programado o manual no se completó, o una restauración a un punto en el tiempo no encontró nada que copiarOwners, adminsbackup_id, database, backup_kind, finished_at
backup.succeededUn backup terminó (es frecuente, así que no se envía por email salvo que lo actives)nadiebackup_id, database, backup_kind, bytes, finished_at
restore.finishedUna restauración en una base de datos nueva terminó bien o fallóOwners, adminsrestore_id, backup_id, status, database, source_database, finished_at
export.readyUna exportación de una base de datos terminó y se puede descargar. Quien la pidió también recibe su propio email, una vezOwners, adminsexport_id, database, expires_at
engine.failingEl 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, adminsfailures_last_hour, out_of_memory
engine.out_of_memoryUna 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, adminsfailures_last_hour, plan
usage.thresholdSe usó el 80% o el 100% de una cuota (almacenamiento, escrituras, lecturas) en este periodoOwners, adminsmetric, threshold, period_end
spend_cap.reachedEl spend cap (o la cuota de Free) detuvo las escrituras o las lecturas hasta que se reinicie el periodoOwners, adminsblocked, metric, period_end
org.pausedUna organización Free se pausó después de 7 días sin actividadOwnerspaused_at
org.suspendedNamiDB suspendió la organizaciónOwners, adminssuspended_at, reason
api_key.expiringUna API key vence en 7 días o en 1 díaOwners, adminswindow, 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:

CabeceraValor
NamiDB-EventEl tipo de evento, por ejemplo backup.failed
NamiDB-DeliveryEl id de la entrega: es el mismo en todos los reintentos, así que úsalo para deduplicar
NamiDB-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
User-AgentNamiDB-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);
}

Rotate secret emite un secreto nuevo de inmediato; actualiza tu receptor justo después de rotarlo.

Respuestas y reintentos

  • Responde con cualquier estado 2xx en 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 el id del payload) y usa created_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.