---
sidebar_label: Notifications
description: Build automated workflows and real-time alerts by routing platform events through configurable notification channels, filters, and event payloads.
keywords:
  - notifications
  - webhooks
  - event payloads
  - automation
  - real-time alerts
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Notifications

The **notifications system** lets you automate workflows, build audit trails, and get real-time alerts for any change that happens in nullplatform, from new deployments to parameter approvals.

Notifications are fully configurable: you decide **where** they go, **what** they contain, and **when** they’re sent.


:::tip
Notifications integrate with other platform features like deployments, parameters, and telemetry, making it easy to observe, control, and automate everything from a single source of truth.
:::

## How it works

Every notification follows the same flow:

1. **An event occurs**: a platform event from one of the [sources](/docs/notifications/sources-and-actions) (approvals, services, audits, alerts, entities, telemetry, or parameters) triggers a notification.
2. **Filters decide** whether the event should generate a notification.
3. **Channels deliver** the resulting event to notification systems such as Slack, webhooks, or your agent.
4. **Event payloads** define the JSON structure sent to each destination.

This architecture enables deep integration with your organization’s tools and infrastructure.

```mermaid
flowchart TD
    A[Event occurs] --> B[Filters evaluate conditions]
    B -->|Matches filter| C[Channels deliver notification]
    C --> D[Event payload sent to destination]
    D --> E[Notification system receives event: Slack, Webhook, Agent, etc.]
```

## Key components

### Channels: where notifications go
Channels define the **destination** for notification data. You can route events to:

- **Slack** for team alerts and approvals
- **HTTP Webhooks** to trigger custom automation logic
- **Agent** to execute actions inside your own infrastructure
- **GitHub / GitLab / Azure** to integrate deployment events with your CI/CD workflows

### Filters: which notifications are sent
Filters control **what** gets sent to each channel. They use **MongoDB query syntax** to express conditions like:

```json
"filters": {
  "$or": [{ "action": "scope:stop" }, { "action": "scope:delete" }]
}
```

With filters you can:

- Send approval requests only for certain namespaces
- Exclude `deployment:create` events from general audit notifications
- Target alerts by entity, team, or environment

### Sources and actions: what triggers notifications
Every channel listens to one or more **sources**, which are categories of platform events like approvals, audits, or telemetry. Each source produces specific **actions** (for example, `deployment:create` or `audit:log`). See [Sources & actions](/docs/notifications/sources-and-actions) for the full reference.

### Event payloads: what the notification contains
Each notification carries a structured **JSON payload** describing the triggered event. This payload mirrors nullplatform’s public API responses, so you can parse and enrich it easily in external systems.

You can inspect, list, or **resend notification events** for debugging or replaying failed deliveries through the [Notification Events API](/docs/event-api-index).



## Common use cases

- **Approval workflows**: post approval requests to Slack or a webhook endpoint automatically
- **Auditing**: keep a complete record of entity changes and API interactions by routing `audit` events to your SIEM
- **Custom automations**: execute actions in your infrastructure via Agent channels
- **Monitoring**: stream deployment or telemetry data to external observability tools
- **Parameter tracking**: get notified when secrets or configuration values change
- **Entity hooks**: run pre/post-processing logic when entities are created or modified. See [Entity hooks](/docs/entity-hooks/)
- **CI/CD integration**: trigger GitHub Actions, GitLab CI, or Azure Pipelines for service provisioning

## Managing notifications

You can create, list, update, and delete notification channels through:

- **UI:** Go to **Platform settings → Notifications**.
- **CLI:** Use `np notification channel`. (See our [CLI docs](/docs/cli))
- **API:** Use the [Notification API](/docs/notification-api-index).

For step-by-step instructions on listing, updating, and deleting channels, see [Manage channels](/docs/notifications/manage-channels).



## Next steps

- [Understand sources and actions](/docs/notifications/sources-and-actions)
- [Configure channels](/docs/notifications/channels)
- [Manage existing channels](/docs/notifications/manage-channels)
- [Apply filters to route events](/docs/notifications/filters)
- [Inspect event payloads and resend notifications](/docs/notifications/event-payloads)