Skip to main content

Set up 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.

Example use cases​

  • Run a script when a service is updated
  • Notify your CI/CD system when a scope completes
  • Trigger cleanup after a failure or timeout
  • Chain scopes or actions based on event types
  • Stream logs and metrics from your own telemetry systems

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.

Create a channel​

You can create a notification channel from the UI or via API/CLI. Each channel defines how and when your agent should respond to platform events.

Supported types

You can configure the channel using:

  • "type": "agent": (default) Executes a local script through the agent
  • "type": "http": Sends a request to a remote HTTP handler

Before you begin​

Make sure you have an API key with the agent role assigned at the account level. The setup will not work otherwise.

Depending on your use case, you may need to assign additional roles (e.g., ops, secops, etc.) to this key.

  1. Go to Platform settings > Channels and click + New channel.
  2. Set the source (e.g Service or Telemetry).
  3. Select Agent as the type.
  4. Fill in configuration, then click Create channel.

From the CLI or API​

If you want to automate this or manage it in code, see our API reference details and examples.

Examples​

Trigger a script on service events​

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

{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "source": ["service"],
  "type": "agent",
  "configuration": {
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
    "command": {
      "type": "exec",
      "data": {
        "cmdline": "entrypoint.sh --service-path=\"$SERVICE_PATH\"",
        "environment": {
          "NP_ACTION_CONTEXT": "${NOTIFICATION_CONTEXT}"
        }
      }
    },
    "selector": {
      "environment": "local"
    }
  },
  "filters": {
    "service.specification.slug": "$service-spec-slug"
  }
}

Trigger a script for telemetry actions​

This example listens for telemetry events and forwards log or metric requests to your internal script or service.

The agent will automatically forward supported telemetry actions (like log:read, metric:list, metric:data, instance:list) to your handler.

{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "source": ["telemetry"],
  "type": "agent",
  "configuration": {
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
    "command": {
      "type": "exec",
      "data": {
        "cmdline": "entrypoint.sh --service-path=\"$SERVICE_PATH\"",
        "environment": {
          "NP_ACTION_CONTEXT": "${NOTIFICATION_CONTEXT}"
        }
      }
    },
    "selector": {
      "environment": "local"
    }
  },
  "filters": {
    "service.specification.slug": "$service-spec-slug"
  }
}