Configuration

config.json defines the servers, contexts, and global settings that the Cloudflare Worker reads at runtime.

Overview

The configuration lives in a single config.json file managed through the CLI (never edited by hand in production). The file is gitignored — only config.sample.json is committed.

The config has three top-level sections: servers, contexts, and settings.

Settings

Field	Type	Description
`worker_name`	`string`	Name of the Cloudflare Worker, used in wrangler.toml generation. Use lowercase letters, digits, and hyphens, without a hyphen at the start or end.
`base_domain`	`string`	The domain under which all context subdomains are registered (e.g., `ntfy.example.com`). Lowercase letters, digits, hyphens, and dots, with at least two labels.
`show_response_output`	`boolean`	When `true`, POST/PUT responses include detailed debug output (context, interpreter, server results). Set to `false` in production to avoid leaking information.

warning

Keep show_response_output set to false in production. Enabling it exposes context names, interpreter types, and per-server delivery results in HTTP responses.

Servers

Each server represents an ntfy instance. Servers are defined once and referenced by name from contexts.

Field	Type	Description
`name`	`string`	Unique identifier for this server. Referenced by contexts in `primary_server` and `servers` fields.
`server`	`string`	Full URL of the ntfy server (must start with `https://`).
`token`	`string`	Access token for the ntfy server (must start with `tk_`). Created via the ntfy CLI.

json

{
  "name": "primary",
  "server": "https://ntfy.example.com",
  "token": "tk_your_token_here"
}

Contexts

Contexts define notification sources. Each webhook source or email sender maps to one context. There are two types: HTTP contexts and email contexts.

HTTP Context

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier that becomes the subdomain in the route (e.g., `{id}.ntfy.example.com`). Use 1–63 lowercase letters, digits, or hyphens; a hyphen cannot be first or last. The CLI generates one when you leave it blank.
`name`	`string`	Yes	Human-readable name for display in CLI and responses.
`type`	`"http"`	Yes	Must be `"http"` for webhook contexts.
`interpreter`	`string`	Yes	Which interpreter to use. One of: `plain-text`, `ntfy-json`, `statuspage`, `synology`, `seerr`, `pfsense`, `unifi`, `transmission-vpn`, `pfsense-actions`, `discord-stonker-bot`, `outpost`.
`topic`	`string`	Yes	The ntfy topic to publish to.
`error_topic`	`string`	No	Optional ntfy topic where authentication and interpretation errors are sent as one-shot JSON debug attachments outside the durable lane.
`error_events`	`string[]`	No	Which error categories notify `error_topic`. Any of `authentication`, `interpretation`. Omit to notify on both (the default); set to `["interpretation"]` to keep interpreter-error alerts while silencing authentication-failure noise. No effect unless `error_topic` is set.
`mode`	`string`	Yes	Delivery mode: `"send-once"` or `"send-all"`.
`show_visitor_info`	`boolean`	Yes	When `true`, appends visitor IP, location, and ISP details to the notification body.
`primary_server`	`string`	Yes	Name of the preferred server, which must match a server's `name` and appear in `servers`. Tried first in `send-once` mode.
`servers`	`string[]`	Yes	Ordered list of server names. At least one required.
`token`	`string`	No	Optional authentication token for this context. When set, incoming requests must include `Authorization: Bearer {token}` (or the raw token as the header value).

Email Context

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier. Must match the local part of the email address (e.g., `pfsense` for `[email protected]`). Allows letters, digits, dots, underscores, and dashes.
`name`	`string`	Yes	Human-readable name.
`type`	`"email"`	Yes	Must be `"email"` for email contexts.
`interpreter`	`string`	Yes	Which interpreter to use.
`topic`	`string`	Yes	The ntfy topic to publish to.
`error_topic`	`string`	No	Optional error topic for one-shot JSON diagnostics outside the durable lane.
`error_events`	`string[]`	No	Which error categories notify `error_topic`. Any of `authentication`, `interpretation`. Omit for both (the default); e.g. `["interpretation"]` to mute authentication-failure noise. No effect unless `error_topic` is set.
`mode`	`string`	Yes	Delivery mode: `"send-once"` or `"send-all"`.
`show_visitor_info`	`boolean`	Yes	For email contexts, this setting has no effect — visitor details are only available for HTTP requests.
`primary_server`	`string`	Yes	Preferred server name, which must also appear in `servers`.
`servers`	`string[]`	Yes	Ordered server name list.
`allowed_from`	`string`	No	Sender filter. Supports exact match (`[email protected]`) or wildcard (`*@example.com`). Case-insensitive.

Full Example

This example shows a complete config.json with two servers and a mix of HTTP and email contexts.

json

{
  "servers": [
    {
      "name": "primary",
      "server": "https://ntfy.example.com",
      "token": "tk_replace_with_your_token"
    },
    {
      "name": "fallback",
      "server": "https://ntfy-backup.example.com",
      "token": "tk_replace_with_fallback_token"
    }
  ],
  "contexts": [
    {
      "id": "statuspage-example",
      "name": "GitHub Status",
      "type": "http",
      "interpreter": "statuspage",
      "topic": "github-status",
      "error_topic": "errors",
      "error_events": ["interpretation"],
      "mode": "send-once",
      "show_visitor_info": false,
      "primary_server": "primary",
      "servers": ["primary", "fallback"]
    },
    {
      "id": "seerr-example",
      "name": "Seerr Requests",
      "type": "http",
      "interpreter": "seerr",
      "topic": "media-requests",
      "mode": "send-once",
      "show_visitor_info": false,
      "primary_server": "primary",
      "servers": ["primary"],
      "token": "replace_with_auth_token"
    },
    {
      "id": "synology-example",
      "name": "Synology NAS",
      "type": "http",
      "interpreter": "synology",
      "topic": "nas-alerts",
      "mode": "send-once",
      "show_visitor_info": true,
      "primary_server": "primary",
      "servers": ["primary"],
      "token": "replace_with_auth_token"
    },
    {
      "id": "webhook-example",
      "name": "Generic Webhook",
      "type": "http",
      "interpreter": "plain-text",
      "topic": "webhooks",
      "mode": "send-once",
      "show_visitor_info": true,
      "primary_server": "primary",
      "servers": ["primary"]
    },
    {
      "id": "pfsense",
      "name": "pfSense Firewall",
      "type": "email",
      "interpreter": "pfsense",
      "topic": "firewall",
      "mode": "send-once",
      "show_visitor_info": false,
      "primary_server": "primary",
      "servers": ["primary"],
      "allowed_from": "*@pfsense.local"
    },
    {
      "id": "unifi",
      "name": "UniFi Network",
      "type": "email",
      "interpreter": "unifi",
      "topic": "network",
      "mode": "send-once",
      "show_visitor_info": false,
      "primary_server": "primary",
      "servers": ["primary"],
      "allowed_from": "*@unifi.local"
    }
  ],
  "settings": {
    "worker_name": "ntfy-reverse-proxy",
    "base_domain": "ntfy.example.com",
    "show_response_output": false
  }
}

Validation

The CLI checks the config against its schema whenever it loads it. nrp validate, which deploy also runs, adds the reference and duplicate checks:

Structural — All required fields are present and correctly typed, and a context with a key the schema doesn't know fails.
Server references — Every primary_server and every entry in servers must match an existing server name, and each primary_server must also appear in its context's servers.
Duplicate context IDs — No two contexts can share the same id.
HTTP context IDs — IDs are valid DNS host labels: 1–63 lowercase alphanumeric or hyphen characters, with no leading or trailing hyphen.
Token format — Server tokens must start with tk_.
URL format — Server URLs must be valid and start with https://.
Settings format — worker_name and base_domain must follow the formats in Settings.

tip

Run validation manually with nrp validate, or choose Deploy in the interactive menu, which validates the config before it deploys anything.