Skip to content

Platform

Push notifications

Tested with:Beta on Databasezy · Databasezy API v1

Push sends notifications to your users’ browsers, iPhones and Android phones. Databasezy is the relay, not a push service: your apps register their device with your project, and a send reaches those registered devices through the platform’s own service.

PlatformProviderWhat you set up
Browsers (Chrome, Edge, Firefox, Safari)Web Push with VAPIDNothing: a VAPID key is generated for your project in its cell
iOSApple Push Notification serviceYour APNs key (.p8), its key id, your team id, the bundle id
Android (and iOS apps on the Firebase SDK)Firebase Cloud MessagingYour Firebase project’s service account

Use the exact endpoint from Project settings, including its region, custom domain and public port. The host and port below are placeholders.

  1. Turn it on: Platform services → Push, zb push enable, or PUT /v1/orgs/{org}/projects/{project}/push {"enabled": true}. This opens https://<ref>.us-east.databasezy.com:8443/push/v1 and generates the project’s VAPID key in its cell.

  2. For iOS, upload your APNs key: Platform services → Push → Provider keys, or zb push credentials apns --team-id ABCDE12345 --key-id KEY1234567 --bundle-id com.example.app --environment production --key-file AuthKey_KEY1234567.p8. Use sandbox for builds run from Xcode.

  3. For Android on FCM, upload a service account of your Firebase project with the Firebase Cloud Messaging API Admin role: zb push credentials fcm --service-account-file service-account.json. Its token_uri must be Google’s.

Provider keys are write-only: the API seals them for your project’s cell and keeps a reference, the identifiers and a fingerprint; no read API, log or event returns them. Uploading again rotates a key; zb push credentials rm apns removes it. Uploading a key needs push:write and a recent second factor.

Apps register with the publishable key. Send the signed-in user’s access token too, and the device is bound to that user (its external_id is the token’s sub), so you can send to a user by id.

// The page. VAPID_PUBLIC_KEY: Platform services → Push → Activity, or GET /push/v1/vapid-public-key.
const reg = await navigator.serviceWorker.register("/sw.js");
const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: VAPID_PUBLIC_KEY });
await fetch(`${DATABASEZY_URL}/push/v1/tokens`, {
method: "POST",
headers: {
apikey: DATABASEZY_PUBLISHABLE_KEY,
Authorization: `Bearer ${session.access_token}`, // optional: binds the device to the user
"Content-Type": "application/json",
},
body: JSON.stringify({ platform: "web", subscription: sub.toJSON(), topics: ["news"] }),
});
sw.js
self.addEventListener("push", (event) => {
const { notification = {}, data = {} } = event.data ? event.data.json() : {};
event.waitUntil(
self.registration.showNotification(notification.title ?? "", {
body: notification.body, icon: notification.icon, image: notification.image, data: { url: notification.url, ...data },
}),
);
});
self.addEventListener("notificationclick", (event) => {
event.notification.close();
if (event.notification.data?.url) event.waitUntil(clients.openWindow(event.notification.data.url));
});

POST /push/v1/tokens takes platform (web, ios, android), optionally provider (webpush, apns, fcm; by default the platform’s own; fcm is also accepted for iOS apps on the Firebase SDK), token (APNs, FCM) or subscription (Web Push), and up to 20 topics. It answers 201 (or 200 when the device was already registered) with the device’s id, its external_id, its topics and the token’s last eight characters; the token itself is never returned. Web Push subscriptions must point at a browser’s push service (Google, Mozilla, Apple, Microsoft).

Callerexternal_id
Publishable key alonenone (an anonymous device); naming one is refused (403). It cannot detach a signed-in user’s device either
Publishable key + user’s access tokenthe token’s sub; naming another user is refused (403)
Secret key (your server)whatever you set

Unregister on sign-out, before the session ends: POST /push/v1/tokens/unregister with the same platform and token/subscription (an anonymous device, the user’s own, or any with a secret key), or DELETE /push/v1/tokens/{id} (the user’s own device, or any with a secret key).

POST /push/v1/topics/{topic}/subscribe and …/unsubscribe with {"token_id": "ptk_..."} add or remove a device the caller manages. Topic names have 1 to 128 letters, digits, _, ., ~ or -. Topics starting with user. or private. can only be managed with a secret key, so a client cannot subscribe itself to messages meant for others.

Sends need the secret key (or a function, which has the service role key): POST /push/v1/send from a publishable key or an end user’s token is refused (403), at the edge and in the service.

From your server
await fetch(`${DATABASEZY_URL}/push/v1/send`, {
method: "POST",
headers: { apikey: process.env.DATABASEZY_SECRET_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
target: { external_ids: [userId] }, // or { topic: "news" } or { token_ids: ["ptk_..."] }
notification: { title: "Order shipped", body: "Order #42 is on its way", url: "https://shop.example.com/o/42" },
data: { order_id: "42" },
priority: "high",
idempotency_key: "order-42-shipped",
}),
});
// 202 {"id": "pmsg_...", "status": "queued", "recipients": 2, ...}
From a function
const res = await fetch(`${Deno.env.get("SUPABASE_URL")}/push/v1/send`, {
method: "POST",
headers: { apikey: Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!, "Content-Type": "application/json" },
body: JSON.stringify({ target: { topic: "news" }, notification: { title: "Hello" } }),
});
FieldRule
targetExactly one of token_ids (up to 1 000; every id must be a device of the project, else 403), external_ids (up to 1 000) or topic
notificationtitle (≤ 256 characters) and/or body (≤ 2 048), image, url, icon (https), badge, sound
dataUp to 50 string values (≤ 1 024 bytes each); keys have up to 64 letters, digits, _, . or -; from, notification, message_type, aps, collapse_key, google.* and gcm.* are reserved
ttl_secondsHow long the provider keeps an undelivered message, up to 28 days
prioritynormal or high
collapse_keyUp to 32 letters, digits, _ or -: replaces an undelivered message with the same key
idempotency_keyThe same key within the project returns the first send instead of sending again

The notification and data together must fit 3 800 bytes once encoded for the providers, else 413. A send is queued and delivered by the project’s cell; GET /push/v1/messages/{id} (secret key) shows queued, sending, done or failed with the counts sent, failed and pruned. Payloads are deleted once a send is finished; the send’s metadata is kept 30 days.

A send can only reach devices registered with the project: it names device ids, user ids or a topic, never a raw token or URL, so the relay cannot be used to message anyone else’s devices.

A database webhook with a push target sends a notification for every inserted or updated row, to every device subscribed to a topic, without code in between. It uses the webhook’s durable queue: retries with backoff and dead letters. The portal’s Platform services → Realtime → Database webhooks screen offers HTTPS URL and Project function targets. Configure a push target through the API or CLI; it cannot be selected in that form yet.

create table public.notifications (
id bigint generated always as identity primary key,
title text, body text, url text, data jsonb
);
Terminal window
zb push enable
zb realtime webhooks create --name notify --table public.notifications --events INSERT --push-topic news
# API: POST …/realtime/webhooks {"name": "notify", "schema": "public", "table": "notifications",
# "events": ["INSERT"], "target": "push", "topic": "news"}

The row’s title, body, url and image columns become the notification and its data column (a JSON object) the data; a row with none of title, body or data is refused and dead-lettered. Deletes send nothing. A retried delivery is the same send. Database webhooks need realtime and a primary database on the project, and push enabled.

Each device’s provider answer is counted: accepted notifications are sent; the rest are failed. A device is pruned (removed from the project) only when its provider says it is gone: Web Push 404/410, APNs 410 (Unregistered, ExpiredToken), FCM UNREGISTERED or an invalid registration token. BadDeviceToken from APNs usually means the wrong environment (sandbox token, production key): it fails the delivery but never prunes. A provider refusing your key is reported in the project’s security events. Transient errors are retried.

Free cellsOther cells
Send requests per minute60600
Devices per message1 000100 000
Deliveries per hour10 0001 000 000
Registered devices50 0005 000 000

Above a limit a send is refused (422 for the fan-out, 429 with Retry-After for the rates). A message reaching 1 000 devices on Free cells (10 000 elsewhere) is reported as a security signal to watch for spam through a leaked secret key.

RequestPermission
GET …/projects/{project}/push, …/push/status, …/push/devicespush:read
PUT …/push {"enabled": true, "web_push_subject": "mailto:[email protected]"}push:write
PUT …/push/credentials/apns, …/fcm, DELETE …/push/credentials/{apns,fcm}push:write + recent second factor
POST …/push/test (at most 100 devices)push:write
Terminal window
zb push status # VAPID public key, devices, last day's sends
zb push tokens list --platform ios
zb push send --topic news --title "Hello" --body "From the CLI" # a test (at most 100 devices)
zb push send --external-id u-42 --title "Hi" --secret-key "$DATABASEZY_SECRET_KEY" # a real send

Every change and every test send is in the audit log; enabling, credential changes and refused sends are security events.

Push notifications are free on every plan, like Firebase Cloud Messaging: there is no price and no monthly allowance, only the limits above. Every notification a provider accepts is metered as push_notifications_sent and shown with your project’s usage. Apple and Google do not charge for APNs or FCM delivery; Web Push goes straight to the browser vendor’s push service.