Register Web Push Subscription

POST /api/v1/account/notifications/web_push/subscription

This endpoint registers or refreshes a browser’s push subscription for your account. Pacifica sends web_push notifications to every active subscription on the account. Before you call it, get the VAPID public key from Get Web Push config. Then subscribe in the browser with pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: vapid_public_key }).

Operation Type (for Signing)

Header Field	Type	Content
`"type"`	string	`"register_web_push_subscription"`

Request Body

Field	Type	Need	Description	Example
`”account”`	string	required	User’s wallet address	`42trU9A5…`
`“signature”`	string	required	Cryptographic signature	`5j1Vy9Uq…`
`“timestamp”`	integer	required	Current timestamp in milliseconds	`1716200000000`
`”installation_id”`	string	required	ID that your app generates once for this browser. 32 to 64 characters from `A-Z`, `a-z`, `0-9`, `-`, and `_`	`k3Jx9_Qm…`
`“endpoint”`	string	required	The subscription’s `endpoint`. An `https` URL of a supported push service, up to 2048 characters	`https://fcm.googleapis.com/…`
`“p256dh”`	string	required	The subscription’s `p256dh` key, in base64url without padding	`BNcRdreA…`
`“auth”`	string	required	The subscription’s `auth` secret, in base64url without padding	`tBHItJI5…`
`“expiration_time_ms”`	integer	optional	The subscription’s `expirationTime` in milliseconds. Leave it out when the browser returns `null`	`1735689600000`
`”vapid_public_key”`	string	required	The VAPID public key that you subscribed with	`BF6x0Kq2…`
`“expiry_window”`	integer	optional	Signature expiry in milliseconds	`30000`

{
  "account": "42trU9A5...",
  "signature": "5j1Vy9Uq...",
  "timestamp": 1716200000000,
  "installation_id": "k3Jx9_Qm2LpV7nRt4WcY8bZa1HdF6sGe",
  "endpoint": "https://fcm.googleapis.com/fcm/send/dX8f...",
  "p256dh": "BNcRdreA...",
  "auth": "tBHItJI5svbpez7KI4CCXg",
  "vapid_public_key": "BF6x0Kq2...",
  "expiry_window": 30000
}

subscription.toJSON() in the browser gives you endpoint, keys.p256dh, keys.auth, and expirationTime in the right format. You must sign this request with the account key. An agent wallet can’t sign it. Supported Push Services The endpoint host must belong to one of these push services. It must have no port, user name, password, or fragment.

Host	Push service
`fcm.googleapis.com`	Google
`jmt17.google.com`	Google
`*.push.services.mozilla.com`	Mozilla
`*.push.apple.com`	Apple
`*.notify.windows.com`	Microsoft

Registration Rules

installation_id identifies one browser. Store it where the page and the service worker can both read it, for example IndexedDB.
When you register again with the same installation_id, Pacifica refreshes the subscription.
If the same installation_id registers under another account, the subscription moves to that account.
If another account has an active subscription with the same endpoint and a different installation_id, the request fails with status 409. Unregister it from the other account first.
An account keeps up to 10 active subscriptions. When you register one more, Pacifica turns off the subscription that was registered longest ago.
vapid_public_key must match the current key from Get Web Push config. If it doesn’t, subscribe again with the current key.

After you register, turn on web_push with Set notification master preference and Set notification preference.

Signing

Sign the subscription fields as the data object. The secret goes in data as auth. If you leave out expiration_time_ms, leave it out of data too. For the request above, the message to sign is:

{"data":{"auth":"tBHItJI5svbpez7KI4CCXg","endpoint":"https://fcm.googleapis.com/fcm/send/dX8f...","installation_id":"k3Jx9_Qm2LpV7nRt4WcY8bZa1HdF6sGe","p256dh":"BNcRdreA...","vapid_public_key":"BF6x0Kq2..."},"expiry_window":30000,"timestamp":1716200000000,"type":"register_web_push_subscription"}

Response

Status 200: Subscription registered

{
  "success": true,
  "data": {
    "subscription_id": "3f1c2a7e-9b4d-4e8a-8c2f-6d5b1a0e9f47",
    "vapid_public_key": "BF6x0Kq2..."
  },
  "error": null,
  "code": null
}

Field	Type	Description
`”subscription_id”`	UUID	Subscription ID. Each push carries it as `subscription_id`. It stays the same when you register an active subscription again with the same account, endpoint, keys, and VAPID key. Otherwise Pacifica gives a new ID
`”vapid_public_key”`	string	VAPID public key of the subscription

Status 400: Invalid request parameters or signature. The error_id field says why:

`error_id`	Meaning
`invalid_notification_device_id`	`installation_id` doesn’t have 32 to 64 allowed characters
`invalid_web_push_subscription`	`endpoint`, `p256dh`, `auth`, or `expiration_time_ms` isn’t valid
`unsupported_web_push_service`	The `endpoint` host isn’t a supported push service

Status 403: The account doesn’t exist. An account exists after its first deposit
Status 409: The request conflicts with the current state. The error_id field says why:

`error_id`	Meaning
`web_push_key_mismatch`	`vapid_public_key` isn’t the current key. Subscribe again with the current key
`web_push_endpoint_conflict`	Another account has an active subscription with this `endpoint`
`web_push_disabled`	Web Push isn’t available

{
  "success": false,
  "data": null,
  "error": "Subscription uses an old VAPID key; resubscribe with the current public key",
  "code": 409,
  "error_id": "web_push_key_mismatch"
}

Status 429: Rate limit exceeded
Status 500: Internal server error

Code Example (Python)

import requests

payload = {
    "account": "42trU9A5...",
    "signature": "5j1Vy9Uq...",
    "timestamp": 1716200000000,
    "installation_id": "k3Jx9_Qm2LpV7nRt4WcY8bZa1HdF6sGe",
    "endpoint": "https://fcm.googleapis.com/fcm/send/dX8f...",
    "p256dh": "BNcRdreA...",
    "auth": "tBHItJI5svbpez7KI4CCXg",
    "vapid_public_key": "BF6x0Kq2..."
}

response = requests.post(
    "/api/v1/account/notifications/web_push/subscription",
    json=payload,
    headers={"Content-Type": "application/json"}
)

data = response.json()

​Operation Type (for Signing)

​Request Body

​Signing

​Response

​Code Example (Python)

Operation Type (for Signing)

Request Body

Signing

Response

Code Example (Python)