Configuration

Understand the structure of config.json and how to configure servers, contexts, and global settings.

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: settings, servers, and contexts.

Settings

Field	Type	Description
`worker_name`	`string`	Name of the Cloudflare Worker. Used in wrangler.toml generation.
`base_domain`	`string`	The domain under which all context subdomains are registered (e.g., `ntfy.example.com`).
`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.

{
  "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. Becomes the subdomain in the route (e.g., `{id}.ntfy.example.com`). Auto-generated by the CLI.
`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`.
`topic`	`string`	Yes	The ntfy topic to publish to.
`error_topic`	`string`	No	Optional ntfy topic where authentication and interpretation errors are sent as JSON debug attachments.
`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 (must match a server's `name`). 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}`.

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.
`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.
`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.

{
  "settings": {
    "worker_name": "ntfy-reverse-proxy",
    "base_domain": "ntfy.example.com",
    "show_response_output": false
  },
  "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": "replace_with_random_string",
      "name": "GitHub Status",
      "type": "http",
      "interpreter": "statuspage",
      "topic": "github-status",
      "error_topic": "errors",
      "mode": "send-once",
      "show_visitor_info": false,
      "primary_server": "primary",
      "servers": ["primary", "fallback"]
    },
    {
      "id": "replace_with_random_string",
      "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": "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"
    }
  ]
}

Validation

The CLI validates config against its schema on every load. Validation checks include:

Structural — All required fields are present and correctly typed.
Server references — Every primary_server and every entry in servers must match an existing server name.
Duplicate context IDs — No two contexts can share the same id.
Token format — Server tokens must start with tk_.
URL format — Server URLs must start with https://.

tip

Run validation manually with npm run manage validate or through the interactive menu to catch issues before deployment.