Skip to main content

​
Overview

Notifications surface async events from across your buyer workspace — campaign health, creative approvals, agent registrations, optimization suggestions, and more — through three channels: in-app (per-user feed), email (customer-scoped), and Slack (customer-scoped webhook). In-app opt-ins are tuned per user; email and Slack are admin-managed at the customer level. The v2 notification system gives every operator a structured event feed for things they care about — campaign health, creative approvals, agent registrations, optimization suggestions, and more. Each event is delivered to one or more channels (in_app, email, Slack), and every user opts into the events they want to see.
All endpoints below are mounted under https://api.agentic.scope3.com/api/buyer/. The notification feed is filtered server-side by your in_app opt-ins — users who have not opted into any types see an empty feed.

​
Event taxonomy

Notification types follow a resource.action taxonomy so agents can build workflows around stable event names. The full enum lives in apps/api/src/types/notifications.ts. A representative slice:

Campaign lifecycle

campaign.created, campaign.updated, campaign.healthy, campaign.unhealthy, campaign.completed, campaign.deleted

Creative review

creative.approved, creative.rejected, creative.changes_requested, creative.sync_started, creative.sync_completed, creative.sync_failed

Agent registry

salesagent.registered, salesagent.available, signalsagent.registered, outcomesagent.registered, salesagent.updated

Optimization

optimization.suggestion_received, optimization.suggestion_approved, optimization.suggestion_applied, optimization.suggestion_failed

Measurement & learning

measurement.received, measurement.stale, learning_cycle.completed, hypothesis.proven, hypothesis.disproven

System & syndication

system.warning, system.error, syndication.completed, syndication.failed, audience.synced
Each notification carries a status (success, error, warning, info) and a data object with resource IDs (campaignId, creativeId, salesAgentId, …) plus a human-readable message.

​
Channels

ChannelConfigurationBest for
in_appPer-user opt-ins via PUT /notification-preferencesLive operator UI feed
emailCustomer-level opt-ins + a notificationEmail recipientCritical alerts, audit trail
SlackCustomer-level webhook + per-event-type filterTeam channels, war rooms
email and Slack opt-ins are customer-scoped and managed by admins. in_app opt-ins are per-user so individuals can tune their personal feed.

​
Per-user in-app preferences

Operators control which events appear in their personal feed.
1

List the user's current opt-ins

curl https://api.agentic.scope3.com/api/buyer/notification-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
Returns { "optIns": [{ "notificationType": "campaign.unhealthy", "channel": "in_app" }, ...] }.
2

Replace opt-ins (full set)

PUT /notification-preferences replaces the user’s entire opt-in list. Send up to 200 entries.
curl -X PUT https://api.agentic.scope3.com/api/buyer/notification-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optIns": [
      { "notificationType": "campaign.unhealthy", "channel": "in_app" },
      { "notificationType": "creative.rejected", "channel": "in_app" },
      { "notificationType": "salesagent.registered", "channel": "in_app" }
    ]
  }'

​
Customer-level email opt-ins (admin)

Admins set the recipient address and which event types should generate email.
Changing notificationEmail is sensitive — the recipient receives every email-routed event for the customer (including alert details that may contain campaign IDs and account context). Treat the field like any other admin credential: restrict who can edit it, and audit changes. Mutations to notificationEmail are recorded on the audit log and visible in the buyer activity feed.
curl -X PUT https://api.agentic.scope3.com/api/buyer/notification-email \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notificationEmail": "alerts@brand.example.com" }'
PUT /notification-email and PUT /notification-email/opt-ins require the caller to have the ADMIN or SUPER_ADMIN role. Pass notificationEmail: null to clear the recipient (the platform will then fall back to the customer billing email).

​
Slack configuration (admin)

Slack delivery uses an Incoming Webhook URL. Webhooks are admin-only and stored at the customer level.
Email opt-ins and Slack enabledEventTypes are independent filters. The customer-level email opt-in list (/notification-email/opt-ins) controls which events generate email; the Slack enabledEventTypes list on /slack-configuration is a separate per-channel filter applied to Slack delivery only. To get a Slack alert for a given event type, that type must be present in enabledEventTypes — the email opt-in list has no effect on Slack. Configure both lists independently to route the same event to the channels you want.
1

Create or update the webhook

curl -X PUT https://api.agentic.scope3.com/api/buyer/slack-configuration \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://hooks.slack.com/services/T_REPLACE/B_REPLACE/REPLACE_TOKEN",
    "enabled": true,
    "enabledEventTypes": [
      "campaign.unhealthy",
      "creative.rejected",
      "system.error"
    ]
  }'
The URL must start with https://hooks.slack.com/services/. Provide at least one event type — only events on this list are forwarded to Slack.
A Slack incoming-webhook URL is a credential: anyone who has the URL can post messages to that channel without authenticating. Never paste a real webhook URL into source files, tickets, screenshots, or shared docs. Store the URL in a secret manager and rotate it immediately if it leaks (revoke + reissue from the Slack app configuration).
2

Send a test message

curl -X POST https://api.agentic.scope3.com/api/buyer/slack-configuration/test \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
Posts a confirmation message to the configured webhook so the team can verify delivery before relying on it.
3

Read the current configuration

curl https://api.agentic.scope3.com/api/buyer/slack-configuration \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
The response masks the webhook URL by default.
4

Disable Slack delivery

curl -X DELETE https://api.agentic.scope3.com/api/buyer/slack-configuration \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

​
Reading the in-app feed

curl "https://api.agentic.scope3.com/api/buyer/notifications?unreadOnly=true&limit=25" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
Query paramTypeNotes
brandAgentIdnumberLimit to a single brand agent
campaignIdstringLimit to a single campaign
creativeIdstringLimit to a single creative
statusenumsuccess / error / warning / info
typescomma listOne or more NotificationEventType values
unreadOnlytrue / falseHide already-read items
limit1..100Default 50
offsetintPagination cursor
The response includes the page of notifications, plus totalCount, unreadCount, and hasMore for pagination.
The list endpoint already filters to event types the calling user opted into on the in_app channel — there is no need to pass types from the UI. If the user has not opted into any in-app types the response is an empty array (with totalCount: 0).

​
Mark read / acknowledge

A notification has two completion states:
  • read — surfaced to the user; safe to demote in the UI.
  • acknowledged — the user has acted on it (e.g. approved a suggestion). The feed hides acknowledged items by default.
curl -X POST https://api.agentic.scope3.com/api/buyer/notifications/$ID/read \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

​
Endpoint reference

MethodPathPurpose
GET/notificationsList in-app notifications (filtered by user opt-ins)
POST/notifications/read-allMark all visible notifications read
POST/notifications/:id/readMark one notification read
POST/notifications/:id/acknowledgeMark one notification acknowledged
GET/notification-preferencesList the calling user’s in-app opt-ins
PUT/notification-preferencesReplace the user’s in-app opt-ins
GET/notification-emailRead the customer’s email recipient
PUT/notification-emailSet the email recipient (admin)
GET/notification-email/opt-insList customer-level email/Slack opt-ins
PUT/notification-email/opt-insReplace customer-level opt-ins (admin)
GET/slack-configurationRead Slack webhook config (admin, URL masked)
PUT/slack-configurationCreate or update Slack webhook (admin)
POST/slack-configuration/testSend a test message to the webhook (admin)
DELETE/slack-configurationRemove Slack webhook (admin)
All endpoints validate the standard buyer auth context (customerId, userId, userRole). Admin-only endpoints reject non-admin callers with ACCESS_DENIED.