Notifications

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 (account-scoped), and Slack (account-scoped webhook). In-app opt-ins are tuned per user; email and Slack are admin-managed at the account level. The 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.

Open the notification inbox in Murph

Buyer and storefront agents can open the Notifications Page in Murph. It lists a bounded page of events, lets you load older results, and keeps Read and Acknowledged as separate states. Both states apply only to the signed-in recipient: reading or acknowledging a broadcast event does not change another person’s inbox. The Page also shows the current primary-Slack settings for Product Updates and sustained source-health alerts. Changing delivery does not mark an inbox event read or acknowledged, and a successful Slack, email, or webhook attempt does not count as either action. Release history stays in the separate Release notes Page. For agent builders, v3 open_page({"page":"notifications"}) returns a persona-specific Page contract. Buyer and storefront operation aliases are explicit; if the launch contract is missing, the Page waits instead of silently trying another API surface.

All endpoints below are mounted under https://api.interchange.io/api/v2/ and are accessible to both buyer and storefront users (role-agnostic shared router). The notification feed is filtered server-side by your in_app opt-ins plus always-on operational event types. A user with no opt-ins can therefore still see required storefront health and approval events.

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

Storefront health & approvals (always-on)

inventory_source.unhealthy, source.action_required, source.action_resolved, salesagent.sync_action_required, storefront_adapter_credential.action_required, storefront.composition_paused, storefront.products_not_traffickable, storefront.liveness_degraded, storefront.liveness_recovered, media_buy.approval_requested, creative.review_requested, ad_server.approval_requested, inventory_shortfall.review_requested — operational alerts that bypass opt-in for the in-app feed. Storefront health/readiness, ad-server approval, and inventory-shortfall alerts use account notification settings. Media-buy and creative-review queue alerts use the primary or optional escalation audience configured for that approval class; email is sent only when the routing stage enables email. Slack is the one exception: even always-on types only post to Slack once you’ve added that event type to your Slack configuration’s enabled events — connecting Slack doesn’t turn these on by itself.

Optimization suggestions notify you only when there’s a decision to make. You get optimization.suggestion_received when a suggestion proposes a budget or bid change on a campaign and media buy that are both still active. A suggestion that carries no budget or bid change doesn’t notify — most often a media buy with no optimization goal, where the suggestion is pacing information only, but also any run where the optimizer settles on your current allocation. Neither does a suggestion whose campaign or media buy is no longer active by the time it reaches you. In both cases the suggestion is still recorded against the media buy and closed out, so nothing sits in your queue waiting on a decision you can’t make.

Your storefront’s liveness verdict flipping is a proactive notification. When the liveness.state on Get readiness flips away from live (to live_attention or live_critical), or a further worsening from live_attention to live_critical, you get a storefront.liveness_degraded notification carrying the verdict’s own reason line and fix path — you don’t have to notice the dot change color. Recovery back to live sends storefront.liveness_recovered. A storefront still in setup (state: "setup") never alerts — setup is not failure. Repeated sweeps of the same unchanged state never re-notify.

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

Pending storefront review now sends a notification. When a buyer submits a creative or media buy that’s waiting on a storefront operator’s decision, it still appears in the operator’s Approvals queue and via Murph — and it also notifies the configured approval audience. In-app is always on; email and Slack follow that approval class’s routing rule. See Reviewing buyer transactions for how operators review and act on pending items.

Synchronous creative sync errors

Creative sync failures are not always reported as notifications. When a media-buy create or update targets a library-only seller and sync_creatives fails before the media-buy request is sent, the API returns a synchronous error instead of continuing silently. Handle this as an API failure and retry after correcting the creative or seller issue. The message includes the seller and cause:

Creative sync to sales agent {id} failed before media buy update: {reason}

Channels

Channel	Configuration	Best for
`in_app`	Per-user opt-ins via `PUT /notification-preferences`	Live operator UI feed
`email`	Account-level `notificationEmail` plus event-specific user delivery	Critical alerts, audit trail
Slack	Account-level webhook + per-event-type filter	Team channels, war rooms

email and Slack opt-ins are account-scoped and managed by admins. in_app opt-ins are per-user so individuals can tune their personal feed. Approval work for media buys and creative review is different: the approval routing rule names its primary users and any optional escalation users, and its channel settings decide whether those users also receive email or the customer Slack channel receives one post. A missing account notification email does not broadcast those routed approval classes to every active user. Ad-server and inventory-shortfall approvals still use account notification settings until dedicated routes are available.

Per-user in-app preferences

Operators control which events appear in their personal feed.

List the user's current opt-ins

curl https://api.interchange.io/api/v2/notification-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Returns { "optIns": [{ "notificationType": "campaign.unhealthy", "channel": "in_app" }, ...] }.

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.interchange.io/api/v2/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" }
    ]
  }'

Account-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 account (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.interchange.io/api/v2/notification-email \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notificationEmail": "alerts@brand.example.com" }'

curl https://api.interchange.io/api/v2/notification-email \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X PUT https://api.interchange.io/api/v2/notification-email/opt-ins \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optIns": [
      { "notificationType": "campaign.unhealthy", "channel": "email" },
      { "notificationType": "creative.rejected",  "channel": "email" }
    ]
  }'

curl https://api.interchange.io/api/v2/notification-email/opt-ins \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

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 account-wide recipient; per-user email delivery still follows the rules above.

Slack configuration (admin)

Slack delivery uses an Incoming Webhook URL. Webhooks are admin-only and stored at the account level.

Murph channel delivery settings

Product Updates and source outage alerts use your account’s primary Murph Slack channel rather than the incoming-webhook event filter above. An active account member can ask Murph to show or change these settings; Murph confirms the write before applying it. You can also use the shared v2 API:

List primary-channel delivery settings

curl https://api.interchange.io/api/v2/notification-delivery-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Turn off Product Updates in the primary channel

curl -X PUT https://api.interchange.io/api/v2/notification-delivery-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stream": "product_updates", "enabled": false }'

Send a Slack alert after a source outage lasts 30 minutes

curl -X PUT https://api.interchange.io/api/v2/notification-delivery-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "source_health_alerts",
    "enabled": true,
    "thresholdMinutes": 30
  }'

Source outage Slack alerts can be sent after 10, 30, or 60 minutes, or turned off. Each alert also includes controls for future outages. Turning these Slack alerts off does not disable immediate in-app or email health notifications. Product Updates currently support on/off only. Their delivery schedule is fixed; the API does not expose a frequency value that the sender cannot honor.

Email opt-ins and Slack enabledEventTypes are independent filters. The account-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.

Create or update the webhook

curl -X PUT https://api.interchange.io/api/v2/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).

Send a test message

curl -X POST https://api.interchange.io/api/v2/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.

Read the current configuration

curl https://api.interchange.io/api/v2/slack-configuration \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

The response masks the webhook URL by default.

Disable Slack delivery

curl -X DELETE https://api.interchange.io/api/v2/slack-configuration \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Reading the in-app feed

curl "https://api.interchange.io/api/v2/notifications?unreadOnly=true&limit=25" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Query param	Type	Notes
`brandAgentId`	number	Limit to a single brand agent
`campaignId`	string	Limit to a single campaign
`creativeId`	string	Limit to a single creative
`status`	enum	`success` / `error` / `warning` / `info`
`types`	comma list	One or more `NotificationEventType` values
`unreadOnly`	`true` / `false`	Hide already-read items
`limit`	1..100	Default 50
`offset`	int	Number of items to skip (offset-based pagination)

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.interchange.io/api/v2/notifications/$ID/read \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X POST https://api.interchange.io/api/v2/notifications/read-all \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "brandAgentId": 12345 }'

curl -X POST https://api.interchange.io/api/v2/notifications/$ID/acknowledge \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Endpoint reference

Method	Path	Purpose
`GET`	`/notifications`	List in-app notifications (filtered by user opt-ins)
`POST`	`/notifications/read-all`	Mark all visible notifications read
`POST`	`/notifications/:id/read`	Mark one notification read
`POST`	`/notifications/:id/acknowledge`	Mark one notification acknowledged
`GET`	`/storefront/approval-routing`	List approval audiences, channels, and SLA settings
`PUT`	`/storefront/approval-routing/:kind`	Replace routing for `MEDIA_BUY` or `CREATIVE_REVIEW` (admin)
`GET`	`/notification-preferences`	List the calling user’s in-app opt-ins
`PUT`	`/notification-preferences`	Replace the user’s in-app opt-ins
`GET`	`/notification-email`	Read the account’s email recipient
`PUT`	`/notification-email`	Set the email recipient (admin)
`GET`	`/notification-email/opt-ins`	List account-level email/Slack opt-ins
`PUT`	`/notification-email/opt-ins`	Replace account-level opt-ins (admin)
`GET`	`/slack-configuration`	Read Slack webhook config (admin, URL masked)
`PUT`	`/slack-configuration`	Create or update Slack webhook (admin)
`POST`	`/slack-configuration/test`	Send a test message to the webhook (admin)
`DELETE`	`/slack-configuration`	Remove Slack webhook (admin)

All endpoints validate the standard buyer auth context (customerId, userId, userRole). Admin-only endpoints reject non-admin callers with ACCESS_DENIED.

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Overview

Open the notification inbox in Murph

Event taxonomy

Campaign lifecycle

Creative review

Agent registry

Optimization

Measurement & learning

System & syndication

Storefront health & approvals (always-on)

Synchronous creative sync errors

Channels

Per-user in-app preferences

Account-level email opt-ins (admin)

Slack configuration (admin)

Murph channel delivery settings

Reading the in-app feed

Mark read / acknowledge

Endpoint reference

​Overview

​Open the notification inbox in Murph

​Event taxonomy

Campaign lifecycle

Creative review

Agent registry

Optimization

Measurement & learning

System & syndication

Storefront health & approvals (always-on)

​Synchronous creative sync errors

​Channels

​Per-user in-app preferences

​Account-level email opt-ins (admin)

​Slack configuration (admin)

​Murph channel delivery settings

​Reading the in-app feed

​Mark read / acknowledge

​Endpoint reference

Overview

Open the notification inbox in Murph

Event taxonomy

Synchronous creative sync errors

Channels

Per-user in-app preferences

Account-level email opt-ins (admin)

Slack configuration (admin)

Murph channel delivery settings

Reading the in-app feed

Mark read / acknowledge

Endpoint reference