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
- A platform event (e.g. service deployed) is emitted by nullplatform.
- A configured notification channel picks up the event.
- If the event matches the channel’s tag selector, the agent is notified.
- The agent executes the command you’ve configured (e.g. a local script).
- Logs and results are optionally sent back to the platform for visibility.
Create a channel
Before you start
You’ll need a separate API key with the following roles:
agent
,developer
,ops
,secops
andsecrets-reader
.- Roles must be at the account level level or the setup won’t work.
Set it up
From the UI:
- 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"
}
}