Push Notifications

CampaignOS supports web push notifications via the VAPID protocol.

List Push Subscriptions

`GET /api/workspaces/{workspaceId}/push`

Lists active push subscriptions.

Auth: Session required

Query Parameters:

Param	Type	Description
`contactId`	string	Filter by contact

Response:


[
  {
    "id": "ps_abc123",
    "contactId": "ct_1",
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "topic": "marketing",
    "active": true,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "contact": {
      "id": "ct_1",
      "email": "jane@example.com",
      "firstName": "Jane"
    }
  }
]

Register Push Subscription

`POST /api/workspaces/{workspaceId}/push`

Registers or updates a web push subscription for a contact.

Auth: Session required

Request Body:


{
  "contactId": "ct_abc123",
  "endpoint": "https://fcm.googleapis.com/fcm/send/abc123...",
  "p256dh": "BNcRdreALRFXTkOOUH...",
  "auth": "tBHItJI5svbpC7sc...",
  "topic": "marketing"
}

Field	Type	Required	Description
`contactId`	string	Yes	Contact to associate
`endpoint`	string	Yes	Push service endpoint URL
`p256dh`	string	Yes	Client public key
`auth`	string	Yes	Authentication secret
`topic`	string	No	Topic for topic-based subscriptions

Push via CampaignOS.js

The embedded script handles push subscription automatically:

Script checks if push is enabled for the workspace
Prompts the user for notification permission
Registers the subscription with the CampaignOS API
Subscription is linked to the contact via identity

See Website Script for embedding details.

VAPID Configuration

Set these environment variables for web push:


NEXT_PUBLIC_VAPID_PUBLIC_KEY="your-public-key"
VAPID_PRIVATE_KEY="your-private-key"

Generate VAPID keys:


npx web-push generate-vapid-keys