Terminology
Short, practical definitions for the Context, Interpreter, Pipeline, delivery, and Cloudflare terms used throughout the Reverse Proxy for ntfy documentation. Tables list the term first, also known as, then the definition.
Glossary Terms
Throughout the docs, you will see highlighted terms with a dotted underline. Hover over any of them for a quick reminder of what they mean, or click to jump to the full definition.
How It Works
| Term | Also known as | Definition |
|---|---|---|
| Worker | Cloudflare Worker | The Cloudflare-hosted entry point that receives incoming webhooks and emails and runs them through the pipeline. The CLI is the other runtime, managing config.json locally instead of processing traffic. |
| pipeline | — | The ordered stages a request or email passes through inside the Worker, grouped into Ingress, Processing, and Delivery. HTTP runs 10 stages (Receive through Respond); email runs 9, swapping Receive for Parse Email and Respond for Log. |
| context | contexts entry | A notification source configuration: a subdomain or email address, an interpreter, a topic, a server list, and a delivery mode. Each context is either HTTP or email, and its ID also names its own delivery lane. |
| interpreter | interpreter | A module that turns a raw webhook payload or email into a notification object with a title, body, priority, tags, and other ntfy fields. Built-ins cover Statuspage.io, Synology DSM, Seerr, pfSense, UniFi, Transmission VPN, pfSense Actions, Discord Stonker Bot, Outpost, and Mailmask, plus plain-text and ntfy-JSON modes. |
| notification object | — | The standardized result an interpreter returns, with fields like title, body, priority, tags, icon, actions, and markdown. An optional attachment and its filename travel alongside it, not nested inside it. |
| notification suppression | — | When an interpreter returns null instead of a notification object, intentionally dropping the event. An HTTP context responds with an "ignored" status; an email context drops the message with no reply. |
ntfy Servers and Messages
| Term | Also known as | Definition |
|---|---|---|
| ntfy | — | The open-source push notification service (ntfy.sh) this project delivers to. Reverse Proxy for ntfy sits in front of one or more self-hosted ntfy servers and prepares notifications for them. |
| server | servers entry | An ntfy instance defined by a name, a URL, and an authentication token. Each server is defined once, and any number of contexts can reference it by name. |
| primary server | primary_server | The preferred ntfy server for a context, which send-once tries first before the remaining servers in order. |
| topic | topic | The ntfy channel a context publishes its notifications to. |
| error topic | error_topic | An optional ntfy topic that receives authentication, interpretation, and discarded-delivery details as JSON debug attachments. These one-shot, best-effort diagnostics bypass durable delivery. The error_events setting narrows authentication and interpretation categories, while outbox discard diagnostics remain visible whenever the topic is configured. |
| ntfy headers | — | The 8 outgoing headers the proxy sets from the notification object: X-Title, X-Priority, X-Tags, X-Markdown, X-Icon, X-Actions, X-Attach, and X-Filename. No other headers, like X-Click or incoming request headers, are forwarded. |
| attachment | — | A binary file delivered alongside a notification, such as a binary plain-text body or an error topic's error-debug.json. It is sent as a PUT with its filename header, after any POSTs carrying text parts. |
| smart split | message splitting | Breaks a notification body over 4000 UTF-8 bytes into numbered parts labeled like "(1/3)". It never splits a multi-byte character mid-sequence. |
Delivery Modes and Reliability
| Term | Also known as | Definition |
|---|---|---|
| send-once | mode | A delivery mode that tries the primary server first, then the remaining servers in order, stopping at the first success. If a fallback delivers, a warning that the primary was unreachable is prepended to the body. |
| send-all | mode | A delivery mode that sends to every server in the context's list at the same time, with no failover. |
| delivery outbox | — | SQLite-backed Durable Object storage that saves a fully formatted notification before sending it to ntfy. Transient failures retry by alarm; permanent failures are discarded, and transient rows expire only after 24 hours with at least three failed attempts. |
| delivery lane | — | One context's independent FIFO list of normal notifications inside the delivery outbox. A transiently failed oldest item leads until success or age-based expiry, while other contexts' lanes continue; error-topic diagnostics bypass it. |
| bounded retry | — | A transient notification retries with exponential backoff and remains eligible for at least 24 hours. It can expire only after the age limit and a three-attempt minimum. A crash after ntfy accepts a request but before the proxy records success can still produce a duplicate. |
| Durable Object | — | Cloudflare's strongly consistent Worker storage and coordination primitive. The proxy uses one SQLite-backed Durable Object per context ID for its delivery lane, and the CLI adds its binding and migration to wrangler.toml. |
Configuration
| Term | Also known as | Definition |
|---|---|---|
config.json | — | The single file holding the settings, servers, and contexts sections; deploy ships a copy inside the Worker. The CLI manages it and keeps it gitignored, committing only config.sample.json. |
| debug mode | show_response_output | Adds context, interpreter, and per-server delivery details to responses and to the landing page's collapsible section. Server tokens and URLs always stay masked with ***. |
| landing page | — | The HTML page a context returns on GET requests, with the project logo and name, a short description, an "Operational" badge, and Documentation and GitHub links. With debug mode on, it adds a collapsible section with the masked configuration. |
| session token | session | A signed, short-lived token a sender gets from a context's /session path and spends on its next message. It is tied to the sender's IP address, works once, and expires after 5 minutes by default. |
Cloudflare Setup
| Term | Also known as | Definition |
|---|---|---|
| base domain | base_domain | The single domain, such as ntfy.example.com, under which every context subdomain registers as a custom domain route. It is set once in the global settings. |
| custom domain route | custom_domain = true | A Cloudflare Workers route that treats the hostname's first label as the routable subdomain, letting the Worker match it directly against a context ID. |
| Cloudflare Email Routing | — | The Cloudflare feature that forwards email sent to a context's address, like pfsense@ntfy.example.com, to the Worker. The deploy command configures its rules for every email context. |
| KV namespace | Workers KV | A Workers KV store the Worker uses to track Statuspage.io incident and component state for deduplication, and to count and spend session tokens. Every entry expires on its own, and deploy creates and binds the store automatically. |
wrangler.toml | — | The Workers configuration file the CLI generates from config.json, with routes, the delivery outbox binding and migration, any KV binding, and a main entry. It stays gitignored, and Wrangler reads it to deploy. |
| Bot Fight Mode | Super Bot Fight Mode | A Cloudflare feature that can block automated requests, including legitimate webhooks, with a 403. Pro plans and above can skip the Super Bot Fight Mode variant with a WAF rule; the free plan can only turn it off. |