Skip to content

Alerts and webhooks

The Alerts page (owners and admins) decides who is emailed about operational events, and sends the same events to your own endpoints as signed webhooks: to page someone, post to chat, or open a ticket in your tracker.

Events

EventWhenEmailed by default todata fields
backup.failedA scheduled or manual backup didn’t complete, or a point-in-time restore found nothing to copyOwners, adminsbackup_id, database, backup_kind, finished_at
backup.succeededA backup finished (frequent, so off by email unless you turn it on)nobodybackup_id, database, backup_kind, bytes, finished_at
restore.finishedA restore into a new database succeeded or failedOwners, adminsrestore_id, backup_id, status, database, source_database, finished_at
export.readyA database export finished and can be downloaded. Whoever asked for it also gets their own email, onceOwners, adminsexport_id, database, expires_at
engine.failingThe database engine stopped unexpectedly 3 or more times in an hour (at most one alert every 6 hours)Owners, adminsfailures_last_hour, out_of_memory
engine.out_of_memoryA query or workload used more memory than the plan allows and the engine restarted (at most one alert every 6 hours)Owners, adminsfailures_last_hour, plan
usage.threshold80% or 100% of an allowance (storage, writes, reads) used this periodOwners, adminsmetric, threshold, period_end
spend_cap.reachedThe spend cap (or the Free allowance) stopped writes or reads until the period resetsOwners, adminsblocked, metric, period_end
org.pausedA Free organization was paused after 7 days without activityOwnerspaused_at
org.suspendedNamiDB suspended the organizationOwners, adminssuspended_at, reason
api_key.expiringAn API key expires in 7 days or in 1 dayOwners, adminswindow, keys

For each event you choose which roles are emailed (owners, admins, members), or nobody.

Webhooks

Add up to 10 endpoints per organization. Each has an https URL on a public address and either every event or a chosen list. Creating, changing, rotating or deleting a webhook asks for your second factor when you have one, and is in the audit log.

Payload

Every delivery is a POST with a JSON body:

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

and these headers:

HeaderValue
NamiDB-EventThe event type, e.g. backup.failed
NamiDB-DeliveryThe delivery’s id: the same across retries, so use it to deduplicate
NamiDB-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
User-AgentNamiDB-Webhooks/1.0 (+https://namidb.com)

Send test delivers a webhook.test event right away (never retried).

Verifying the signature

Each endpoint has a signing secret (whsec_…), shown once when you create it or rotate it. The signature is HMAC-SHA256(secret, "<t>.<raw body>") in hex. Compute it over the raw request body, compare in constant time, and reject timestamps more than 5 minutes old.

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 issues a new secret at once; update your receiver right after rotating.

Responding and retries

  • Answer with any 2xx status within 10 seconds. Redirects are not followed, and only the first 4 KB of your answer is read.
  • A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours (8 attempts in all).
  • Deliveries may arrive more than once or out of order: deduplicate on NamiDB-Delivery (or the payload’s id) and use created_at.
  • An endpoint whose last 5 deliveries failed every retry is turned off, with the reason shown on the page. Turn it back on once it is fixed.

The page shows the delivery log (status, response code, time) and recent events. Deliveries and events are kept for 30 days.