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 additional scopes or actions based on event type

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 API.
  3. The Agent API executes the configured script.
  4. The script runs locally and returns logs or results.
  5. The Agent API optionally sends the outcome back to nullplatform.

Create a channel​

Before you start

You’ll need a separate API key with the agent, role assigned at the account level. The setup won’t work without it.

Depending on your use case, you may need to assign additional roles to this API key.

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

From the CLI or API​

If you want to use any of this tools instead, see our API reference for details and request examples.

Example: Trigger a script (type: exec)​

This example runs a shell script when a service event matches the specified tags:

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