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
- Nullplatform emits an event (e.g. service deployed).
- A notification channel forwards the event to your infrastructure’s Agent API.
- The Agent API executes the configured script.
- The script runs locally and returns logs or results.
- 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.
From the UI (Recommended)
- Go to Platform settings > Channels and click + New channel.
- Set the source (e.g Service).
- Select Agent as the type.
- 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"
}
}