Set up an agent notification channel

Agent notification channels let you trigger actions inside your infrastructure in response to events that happen in nullplatform. This allows you to build event-driven workflows that remain fully scoped within your own environment.

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.
• An new API key also with Agent and Ops roles. See Authenticate the agent.

Example: Trigger a script on service events

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

UI (Recommended)

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.

CLI

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"
    }
}'

cURL

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"
    }
}'

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 for more details.

How it works

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

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.