Web Push Experimental

How a device subscribes

The app uses one of two paths, and reports the stage that failed (permission, worker, subscription, registration or saving) if a browser cannot finish.

• Declarative push. When the page is top-level and window.pushManager exists, as in Safari 18.4 and later, the app subscribes straight from the button click, with no service worker.
• Classic push. Otherwise it asks for notification permission, registers service-worker.js at the app's scope, waits up to 15 seconds for it to activate, and subscribes through registration.pushManager.

Parameters

user

The recipient's email address. It defaults to the signed-in user.

topic or t

The topic. wp.rt.ht requires it, and push.rt.ht defaults to RTEdge.net.

truncate

0 or 1. Per-device truncation is on by default. See Delivery.

Body

The body is JSON: either a notification object, or an array [title, options]. A body that is not valid JSON is still sent, as a notification titled "❌ Notify" that carries the parser error.

title

The title. It defaults to Push.

body

The text of the notification.

navigate

The URL that opens when the notification is clicked. It defaults to the app's URL.

actions

An array of { action, title, navigate?, icon? }. You can also write data.actions[name] = ["openWindow", url]. Actions without a target that can be resolved are dropped.

app_badge

The app-icon badge count. See App badges.

Other fields

lang, tag, dir (auto, ltr or rtl), icon, image, badge (URLs are resolved against the app), silent, renotify, requireInteraction, timestamp, vibrate and data.

Response

The answer is a map from each push endpoint to its result:

{ "<endpoint>": { success, status, response: { ok, status, headers, body, json /* or text */ }, fit, appBadge } }

• With no subscriber, the answer is { "error": "no subscriptions" }.
• The encoded JSON of a notification can be up to 4076 bytes. A larger one answers 413 with { error, bytes, limit }.
• fit reports what per-device truncation did.

Delivery

Each notification is sent as a Declarative Web Push message, with web_push: 8030 and mutable: false, authenticated with VAPID, with TTL: 60 and Urgency: high. Per-device truncation clips the title, the body lines and the action titles to what Windows, iOS, Safari, macOS, Android, Linux and ChromeOS show. Pass truncate=0 to turn it off.

App badges

app_badge controls the badge on the app icon:

• Omit it for an automatic increase of 1 on each device.
• null leaves the badge unchanged.
• A non-negative safe integer, or a decimal string of up to 20 digits that is at most 18446744073709551615, sets the count.

POST /:badge with exactly { device } resets the automatic count to 0. It needs a sign-in and a same-origin request, and the device must be subscribed for that user.

From a page

Subscribe a device to the topic in the app first. The button then sends a notification to yourself:

<button id=ping>Notify me</button>
<script type=module>
  const user = 'you@example.com', topic = 'deploys';
  ping.onclick = () => fetch(`https://wp.rt.ht/:notify?${new URLSearchParams({ user, topic })}`, {
    method: 'POST', headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ title: 'Deployed', body: 'new.rt.ht is live', navigate: 'https://new.rt.ht/' })
  }).then(r => r.json()).then(console.log);
</script>

From a worker

A worker sends the same POST with fetch(). Use an absolute URL. An edge worker that fetches another *.rt.ht deployment directly can get a 522, so go through the in.rt.ht gateway instead: https://in.rt.ht/wp/:notify?user=…&topic=…. In the playground, a worker's fetch() is a browser fetch, so CORS applies, and the app answers with the request's origin. Playground and edge differences explains the gateway.

Send when the page loads

<script src=//wp.rt.ht/.js user=you@example.com topic=deploys></script>
<script>addEventListener('load', () => push({ title: 'Hello', body: 'from my page' }))</script>

Subscriptions

POST /:subscribe?topic=<t>

Subscribes a device. t= also works. The body is { subscription: <PushSubscription JSON>, metadata?: { userAgent, userAgentData? } }. The endpoint must be an https: URL with keys.p256dh and keys.auth. A stored subscription with different keys or another app answers 409. metadata.userAgent is at most 2048 characters. The app immediately pushes a confirmation, "You are now subscribed!", and answers { message: "Subscribed", changed, push }.

GET /:subscribe?topic=<t>

Lists { endpoint, expirationTime, keys }. With view=devices it lists devices as { id, provider, app, current, name, metadata, created }. The id is the SHA-256 hash of the push endpoint, in hex, and provider is the host of the push service.

PATCH /:subscribe

With { device, name } it renames a device. A name is at most 80 characters, is shared across topics, and an empty name clears it.

DELETE /:subscribe

With { device } it unsubscribes silently. With { subscription } it also pushes "You are now unsubscribed!". Both answer { message: "Unsubscribed", changed }.