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.
| Platform | Provider | What you set up |
|---|---|---|
| Browsers (Chrome, Edge, Firefox, Safari) | Web Push with VAPID | Nothing: a VAPID key is generated for your project in its cell |
| iOS | Apple Push Notification service | Your APNs key (.p8), its key id, your team id, the bundle id |
| Android (and iOS apps on the Firebase SDK) | Firebase Cloud Messaging | Your 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.
Set up
Section titled “Set up”-
Turn it on: Platform services → Push,
zb push enable, orPUT /v1/orgs/{org}/projects/{project}/push {"enabled": true}. This openshttps://<ref>.us-east.databasezy.com:8443/push/v1and generates the project’s VAPID key in its cell. -
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. Usesandboxfor builds run from Xcode. -
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. Itstoken_urimust 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.
Register devices
Section titled “Register devices”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"] }),});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));});func application(_ app: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken token: Data) { var req = URLRequest(url: URL(string: "\(baseURL)/push/v1/tokens")!) req.httpMethod = "POST" req.setValue(publishableKey, forHTTPHeaderField: "apikey") req.setValue("Bearer \(session.accessToken)", forHTTPHeaderField: "Authorization") req.setValue("application/json", forHTTPHeaderField: "Content-Type") let hex = token.map { String(format: "%02x", $0) }.joined() req.httpBody = try? JSONEncoder().encode(["platform": "ios", "token": hex]) URLSession.shared.dataTask(with: req).resume()}FirebaseMessaging.getInstance().token.addOnSuccessListener { token -> val body = """{"platform":"android","token":"$token"}""" val req = Request.Builder().url("$baseUrl/push/v1/tokens") .header("apikey", publishableKey) .header("Authorization", "Bearer ${session.accessToken}") .post(body.toRequestBody("application/json".toMediaType())).build() client.newCall(req).enqueue(callback)}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).
| Caller | external_id |
|---|---|
| Publishable key alone | none (an anonymous device); naming one is refused (403). It cannot detach a signed-in user’s device either |
| Publishable key + user’s access token | the 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).
Topics
Section titled “Topics”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.
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, ...}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" } }),});| Field | Rule |
|---|---|
target | Exactly 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 |
notification | title (≤ 256 characters) and/or body (≤ 2 048), image, url, icon (https), badge, sound |
data | Up 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_seconds | How long the provider keeps an undelivered message, up to 28 days |
priority | normal or high |
collapse_key | Up to 32 letters, digits, _ or -: replaces an undelivered message with the same key |
idempotency_key | The 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.
Database triggers
Section titled “Database triggers”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);zb push enablezb 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.
Delivery and pruning
Section titled “Delivery and pruning”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.
Limits
Section titled “Limits”| Free cells | Other cells | |
|---|---|---|
| Send requests per minute | 60 | 600 |
| Devices per message | 1 000 | 100 000 |
| Deliveries per hour | 10 000 | 1 000 000 |
| Registered devices | 50 000 | 5 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.
Manage it
Section titled “Manage it”| Request | Permission |
|---|---|
GET …/projects/{project}/push, …/push/status, …/push/devices | push: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 |
zb push status # VAPID public key, devices, last day's sendszb push tokens list --platform ioszb 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 sendEvery change and every test send is in the audit log; enabling, credential changes and refused sends are security events.
Usage and pricing
Section titled “Usage and pricing”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.