Stay informed about important platform updates, alerts, and events by enabling push notifications. You can subscribe to real-time alerts and fine-tune exactly which notifications you receive using our preference management tools.

How the subscription flow works

Before diving into the configuration, here is a quick look at how your application interacts with the platform to manage notifications and preferences.

sequenceDiagram
    participant Client as Your App / Browser
    participant API as Platform API
    participant Push as Push Notification Service

    Client->>API: 1. POST /push/subscribe
    API-->>Client: Subscription Confirmed
    Client->>API: 2. PUT /preference (Customize alerts)
    API-->>Client: Preferences Saved
    Push-->>Client: 3. Delivers targeted notifications

Subscribing to notifications

You can subscribe to push notifications using either an organization-wide scope or a simplified event-based endpoint, depending on your needs.

1. 1

   Choose your subscription scope

   Decide whether you want to receive notifications for a specific organization or general event updates.

   • Organization scope: Best for team members who need alerts about organization-specific activities.

   • Event scope: A simplified endpoint for general platform events.

2. 2

   Send the subscription request

   Make a POST request to the appropriate endpoint to register your device or webhook for push notifications.

   For an Organization:

   curl -X POST https://api.yourdomain.com/v1/organizations/{organization_id}/push/subscribe 
     -H "Authorization: Bearer YOUR_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{"endpoint": "https://your-push-service.com/...", "keys": {"p256dh": "...", "auth": "..."}}'

   For Simplified Events:

   curl -X POST https://api.yourdomain.com/v1/event/push-notification-subscribe 
     -H "Authorization: Bearer YOUR_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{"target_url": "https://your-webhook.com/alerts"}'

3. 3

   Verify your subscription

   Once you receive a successful response (typically a 200 OK or 201 Created), your subscription is active. You will begin receiving push payloads to the registered endpoints.

Managing your preferences

Once subscribed, you might not want to receive alerts for every action. You can manage your user preferences to filter the noise and only get notified about what matters most.

Preference endpoints

Use the following endpoints to view and modify your notification settings:

Example: Updating a preference

To turn off a specific type of notification (for example, email digests or minor alerts), use the PUT /preference endpoint:

curl -X PUT https://api.yourdomain.com/preference 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "key": "notify_on_minor_updates",
    "value": "false"
  }'

Frequently asked questions