Vapid Web Push Notifications
| Schemes | vapid:// |
| Cargo feature | service-vapid |
| Service | https://datatracker.ietf.org/doc/html/draft-thomson-webpush-vapid |
| Body formats | text (first is the default) |
| Attachments | no |
| Title length | no title (merged into the body) |
| Body length | 4,000 characters |
| Body lines | unlimited |
| Request throttle | none |
| Vendor URLs accepted | no |
URL formats
{schema}://{subscriber}
{schema}://{subscriber}/{targets}
{schema} is one of vapid://.
URL tokens
| Token | Meaning | Type | Required | Default | Notes |
|---|---|---|---|---|---|
{subscriber} | API Key | string | yes | secret | |
{targets} | Targets | list | no | separated by / |
Query parameters
| Parameter | Meaning | Type | Default | Notes |
|---|---|---|---|---|
from | API Key | string | sets {subscriber} | |
keyfile | PEM Private KeyFile | string | secret | |
mode | Mode | choice | chrome | one of chrome, firefox, edge, opera, apple |
subfile | Subscripion File | string | secret | |
to | Targets | list | sets {targets} | |
ttl | ttl | int, 0 to 60 | 0 |
The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.
Examples
Rejected URLs:
vapid://
vapid://:@/
vapid://invalid-subscriber
vapid://user@example.com/user1?ttl=-4000
Notes
Vapid / Web Push (vapid://): Web Push messages signed with VAPID keys.
Messages are encrypted per subscription with RFC 8291 (aes128gcm: ephemeral ECDH P-256, HKDF-SHA256, AES-128-GCM) and authorised with an RFC 8292 VAPID ES256 JWT addressed to each endpoint’s origin.
The private key (?keyfile=, PEM) and the subscriptions (?subfile=, JSON) are read from local files or downloaded from http(s):// URLs. Without ?keyfile=, a disk-backed persistent store holds them: private_key.pem (generated on first use, with public_key.pem) and subscriptions.json in the URL’s store directory. Expired (404/410) endpoints are kept in the store (retired, 30 days) and skipped.
Differences with Apprise
- Both files are re-read on every send.
- Expired endpoints are never pruned from the subscription file (Apprise rewrites a writable one) and no starter file is written.