---
sidebar_label: Create a notification channel
toc_max_heading_level: 3
doc_id: 406d447c-1019-47dd-8263-6e2ba587dd10
description: >-
  Create an agent notification channel to connect the agent to nullplatform events.
  Required to complete the agent setup.
keywords:
  - agent
  - notification channels
  - event-driven
  - infrastructure automation
  - webhooks
---

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

# Create a notification channel

This is the final step in the agent setup. The agent is installed and registered, but it stays idle until you connect it to platform events. A notification channel defines which events the agent listens to and what it runs in response.

<!-- :::note
Prerequisites: install and register the agent, create an API key with the Agent role, and ensure the agent tags match the channel selector.
::: -->

## Create a channel

Create a channel to define your agent’s response to platform events.

**Supported types**

You can configure the channel using either of these types:

- `type: agent`: (Default) Executes a local script through the agent 
- `type: http`: ends a request to a remote HTTP handler   


### Prerequisites

- The agent installed. See [Install the agent](/docs/agent/installation).
- An **new** API key also with **Agent** and **Ops** roles. See [Authenticate the agent](authentication.md).

### Example: Trigger a script on service events

This channel listens for `service` events and runs a local script inside your environment:

<Tabs
defaultValue="agent-channel-ui"
values={[
{ label: 'UI (Recommended)', value: 'agent-channel-ui' },
{ label: 'CLI', value: 'agent-channel-cli' },
{ label: 'cURL', value: 'agent-channel-curl' },
]}>
<TabItem value="agent-channel-ui">

1. Go to **Platform settings > Notifications > Channels** and click **+ New channel**.
2. Set the **source** (e.g., *Service*).
3. Select **agent** as the **type** (or **http** for HTTP channels).
4. Fill in configuration, then click **Create channel**.

<img src="/img/agent/agent-channel-ui.png" width="100%" className="helper-image" alt="Create an agent notification channel in the nullplatform UI" />

</TabItem>
<TabItem value="agent-channel-cli">

```bash
np notification channel create \
--body '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "source": [
        "service"
    ],
    "description": "My agent channel for service events",
    "type": "agent",    // or "http" for HTTP channels
    "configuration": {
        "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
        "command": {
            "type": "exec",
            "data": {
                "cmdline": "path-to-entrypoint-file/entrypoint --service-path=\"$SERVICE_PATH\"",
                "environment": {
                    "NP_ACTION_CONTEXT": "${NOTIFICATION_CONTEXT}"
                }
            },
        },
        "selector": {
            "environment": "local"
        }
    },
    "filters": {
        "service.specification.slug": "$service-spec-slug"
    }
}'
```
</TabItem>
<TabItem value="agent-channel-curl">  

```bash
curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "source": [
        "service"
    ],
    "description": "My agent channel for service events",
    "type": "agent",    // or "http" for HTTP channels
    "configuration": {
        "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
        "command": {
            "data": {
                "cmdline": "path-to-entrypoint-file/entrypoint --service-path=\"$SERVICE_PATH\"",
                "environment": {
                    "NP_ACTION_CONTEXT": "${NOTIFICATION_CONTEXT}"
                }
            },
            "type": "exec"
        },
        "selector": {
            "environment": "local"
        }
    },
    "filters": {
        "service.specification.slug": "$service-spec-slug"
    }
}'
```

  </TabItem>
</Tabs>

### Example: Trigger a script for telemetry actions

If you want to handle telemetry events (logs, metrics, instances), set up an agent channel for `telemetry` events. 

👉 See our dedicated documentation on [telemetry](/docs/telemetry/overview) for more details.

## How it works

The diagram below shows the basic flow when a notification channel is triggered:

```mermaid
sequenceDiagram
  autonumber
  participant NP as Nullplatform
  participant Channel as Notification channel
  participant Infra as Your infrastructure (Agent)

  NP->>Channel: Emit event
  Channel->>Infra: Send notification via Agent 
  Infra->>Infra: Execute configured script/scope
  Infra-->>NP: (Optional) Send result/logs
``` 

### What happens step by step

1. Nullplatform emits an event (e.g., service deployed).
2. A notification channel forwards the event to your infrastructure’s agent.
3. The agent runs the configured script or handler.
4. The script executes locally, inside your infrastructure.
5. The agent optionally returns logs or results to nullplatform.