Skip to main content
Triggers turn external events into Nuon actions. This guide walks through creating a trigger, exposing its ingress URL, routing events with rules in your app config, and inspecting the events and dispatches that result.

​
1. Create a trigger

Create a trigger with the CLI. Use a --preset to configure authentication and payload parsing for a known provider:
Without a preset, set the authentication type explicitly. For secret-based types like hmac, Nuon generates a signing secret for the trigger — reveal and rotate it with the secret commands below.
Use --auth-config to supply advanced settings as a JSON object — for example the header to read the signature from, the signature algorithm, or the expected JWT audience. Common flags:

​
2. Get the ingress URL

The ingress URL is the secret endpoint external systems POST events to. Reveal it, then configure it in the sending system:
If a URL is ever leaked, rotate it:

​
3. Route events with rules

Rules decide which events start which targets. Author them in your app config’s triggers.toml, where each [[rules]] entry references a trigger by name, matches events, and declares a target.
triggers.toml
This example targets a runbook, which runs on an existing install and requires no app branch. To run an app branch instead, use the app_branch_run target — see Targets below.

​
Rule fields

A rule must declare at least one of: event_types, a positive filter, or match_all = true.

​
Filters

Each filter compares a value from the payload or headers.
triggers.toml
Supported op values: eq, neq, in, prefix, suffix, contains, gt, gte, lt, lte, regex, exists, not_exists. Omit value for exists and not_exists. Each filter’s value must encode to at most 4096 bytes. To discover which payload paths and headers are available to filter on, use nuon triggers events paths against a received event — see Test and inspect events.

​
Targets

A target is either an install runbook or an app branch run. Run a runbook on a specific install, mapping payload values into runbook inputs. This target requires no app branch:
triggers.toml
Each entry under inputs maps a runbook input name to a singular payload JSONPath. The runbook must be declared in your app config, and install must name an existing install. Alternatively, run an app branch:
triggers.toml
The named app_branch must already be declared in your app config — the rule fails to sync if it doesn’t exist.

​
4. Test and inspect events

List received events for a trigger:
Filter by type or outcome:
Inspect a single event, then replay it to re-run its routing:
Tail events live as they arrive:
Dry-run a local app config against a received event to see what would match, without dispatching. Pass the path to your app TOML with --app-config, and select the event with either --last (most recent event for a trigger) or --event <event-id>:
To discover which fields you can filter on, list the filterable payload paths and request headers for an event:

​
5. Inspect dispatches

A dispatch is one target execution produced by a matching rule. List, inspect, and retry them:

​
Rotating secrets and suspending

Rotate a trigger’s signing secret, or revoke a specific secret, without downtime:
Suspend a trigger to stop processing events without deleting it, then re-enable it later: