Skip to main content

Security

Protect your notification pipeline with context-level authentication, sensitive value masking, and Cloudflare edge security.

HTTP Authentication

Each HTTP context can optionally require a token. When the token field is set on a context, incoming requests must include a matching Authorization header.

Supported header formats:

  • Authorization: Bearer {token} — The standard bearer token format. The Bearer prefix is case-sensitive (lowercase bearer will not match).
  • Authorization: {token} — A raw token without the Bearer prefix.

If the context has neither a token nor a session field, all requests are allowed without authentication.

danger

On authentication failure, the worker returns HTTP 403. If the context has an error_topic configured and error_events includes "authentication" (or is omitted), an error-debug.json attachment is sent to that topic containing the timestamp, error, context name and interpreter, request details (method, URL, headers with the Authorization header value redacted, and Cloudflare properties), response status, and request body.

json
{
  "timestamp": "2026-04-15T12:00:00.000Z",
  "error": {
    "type": "authentication",
    "message": "Invalid token"
  },
  "context": {
    "name": "My Service",
    "interpreter": "plain-text",
    "stage": "authentication"
  },
  "request": {
    "method": "POST",
    "url": "https://myservice.ntfy.example.com/",
    "headers": {
      "authorization": "REDACTED",
      "content-type": "text/plain",
      "user-agent": "curl/8.0"
    },
    "cf": {
      "country": "US",
      "colo": "SJC"
    }
  },
  "response": {
    "status": 403
  },
  "body": {
    "type": "text",
    "text": "the raw request body"
  }
}

The Authorization header value is redacted (replaced with REDACTED) before sending, and error.message is either Missing Authorization header or Invalid token. Both authentication and interpretation error attachments include a body field with type and json or text sub-fields.

Interpretation error attachments also add the error's name, stack, and any schema issues to error, and they report status 422.

Session Tokens

Session tokens protect a context whose sender's code is public, like an open-source plugin, where a fixed token would be visible to anyone who reads it. Each message needs a fresh session token, so copying a URL and posting to it no longer works.

Session tokens work with every interpreter, because the check runs before the message is interpreted.

How It Works

  1. The sender sends a POST or PUT to https://{id}.ntfy.example.com/session.
  2. The worker replies with a signed session token.
  3. The sender posts its message with Authorization: Bearer {token} from the same IP address.
  4. The worker accepts the message only when it signed the token for this context, the token hasn't expired, the address matches, and the token wasn't used before.
Response from /session
json
{
  "status": "success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOi...",
  "expires_in": 300
}

Limits

  • One message per token — Each session token works once, so a captured request can't be sent again after the first use is recorded. KV checks and writes aren't atomic, so two requests sent at the same instant with one token can both pass.
  • Short lifetime — Tokens expire after ttl_seconds, which defaults to 300 seconds.
  • Per-address limit — Each IP address can get max_per_hour tokens per hour, which defaults to 10. Further /session requests get HTTP 429. The count lives in KV, so a burst of simultaneous requests can slip a few past the limit.
  • Storage — Counting and spending tokens uses the KV namespace that deploy creates. Without it, /session returns HTTP 503.

Rejections

A rejected message gets the same HTTP 403 and error-debug.json behavior as a wrong token. The error.message names the reason:

  • Missing Authorization header
  • Invalid session token
  • Expired session token
  • Session token was issued to another address
  • Session token was already used
  • Session storage is unavailable

info

A public sender's code still shows how to ask for tokens, so anyone can request them the same way. Each token is single-use, short-lived, tied to one address, and capped per hour, which keeps forged traffic small and easy to block.

warning

A context can set token or session, not both. On a context without session, a POST or PUT to /session returns HTTP 404, while a GET still shows the landing page.

tip

If a Cloudflare custom rule blocks every path except / on your proxy's hostnames, add /session to the allowed paths, as the block rule below does. Otherwise Cloudflare answers /session with HTTP 403 before the request reaches the worker, and senders never get a token.

Email Authentication

Email contexts use the allowed_from field to control which senders can trigger notifications.

  • Exact match — user@example.com allows only that address.
  • Wildcard — *@example.com allows any sender from that domain.
  • Not set — All senders are allowed.

Matching is case-insensitive. If the context has an error_topic configured and error_events includes "authentication" (or is omitted), unauthorized emails send an error-debug.json attachment to that topic.

json
{
  "timestamp": "2026-04-15T12:00:00.000Z",
  "error": {
    "type": "authentication",
    "message": "Sender domain not allowed"
  },
  "context": {
    "name": "pfSense Alerts",
    "interpreter": "pfsense",
    "stage": "authentication"
  },
  "email": {
    "from": "unknown@example.com",
    "to": "pfsense@ntfy.example.com",
    "subject": "Alert notification",
    "textBody": "the email's text body"
  }
}

The error.message is Sender domain not allowed for a wildcard rule, Sender not allowed for an exact address, or Missing sender address. Email interpretation errors use the same email object and also add the error's name, stack, and any schema issues.

Sensitive Value Masking

The worker masks sensitive values in the landing page debug section when show_response_output is enabled.

  • Server tokens — Replaced with ***.
  • Server URLs — Replaced with ***.
  • Base domain — Replaced with ***.
  • Context IDs and topics — Replaced with ***.
  • Context tokens, session, and allowed_from — Replaced with *** when present.
  • Error topics — Replaced with *** when present.

This masking applies to the collapsible debug section on the GET landing page. The POST/PUT JSON response includes context name, interpreter, and server results only when show_response_output is enabled.

Debug Output

The show_response_output setting controls whether detailed information is included in responses.

  • Enabled — POST/PUT responses include context name, interpreter, per-server delivery results, and message details. The GET landing page shows a collapsible debug section with the masked config. Useful during initial setup.
  • Disabled — POST/PUT responses include only the delivery status (plus fallback_note when a fallback delivered), and the GET landing page leaves out the debug section. Recommended for production.

Visiting any context URL in a browser (GET request) shows a landing page instead of processing a notification. When show_response_output is enabled, the landing page includes a collapsible section with the full configuration, with sensitive values masked.

When disabled, it shows only the project logo and name, a short description, an "Operational" status badge, links to the documentation and the GitHub repository, and an "A CBN Ventures project" footer.

Cloudflare Edge Protection

Running on Cloudflare Workers provides several security benefits at the edge.

  • Origin IP shielding — Your ntfy server IPs are never exposed to webhook senders.
  • HTTPS enforcement — HTTP requests are automatically redirected to HTTPS via 301 (except on localhost for local development).
  • DDoS protection — Cloudflare's built-in DDoS mitigation applies to all traffic.

WAF Configuration

Cloudflare's bot protection can block legitimate webhooks. You may need to adjust these settings.

  1. Bot Fight Mode (free plan) — Disable this in Dashboard > Security > Bots if automated requests are being blocked with 403 responses. Bot Fight Mode cannot be bypassed with WAF rules.
  2. WAF skip rule (Pro+) — Pro plans and above use Super Bot Fight Mode, which can be skipped. Create a custom rule that skips Super Bot Fight Mode for your proxy's hostnames:
    • If: (http.host contains "ntfy.example.com" and not http.request.headers["sec-fetch-mode"] eq "navigate")
    • Then: Skip all Super Bot Fight Mode rules.
  3. Configuration rule — Set a custom filter to match your proxy hostnames, disable Browser Integrity Check, and set Security Level to "Essentially Off".

warning

Bot Fight Mode cannot be skipped via WAF rules on any plan. The skip rule above targets Super Bot Fight Mode, which is available on Pro plans and above. Free plan users will need to disable Bot Fight Mode entirely if it blocks webhook traffic.

Block Rule

The proxy only answers on / and, for session tokens, on /session. A custom rule that blocks everything else stops scanners at Cloudflare's edge, so they never use up worker requests. The rule works on the free plan.

  1. Open Dashboard > your domain > Security > Security rules and select Create rule > Custom rules.
  2. Name the rule, for example Reverse Proxy for ntfy.
  3. Select Edit expression and paste the expression below. Replace ntfy.example.com with your base_domain.
  4. Set Choose action to Block.
  5. Set Select order to First, then select Deploy.
Expression
text
ends_with(http.host, "ntfy.example.com") and (
  (not http.request.uri.path in {"/" "/session"})
  or (len(http.request.uri.query) > 0)
  or (len(http.request.headers["next-action"]) > 0)
)

Each line blocks one kind of request on your proxy's hostnames:

  • Other paths — Any path besides / and /session, such as /wp-login.php or /.env.
  • Query strings — Any URL with ? parameters, which no sender needs.
  • next-action header — Probes aimed at Next.js server actions, which the proxy doesn't use.

To check the rule, send a POST to https://{id}.ntfy.example.com/session and to any other path, such as /test. The /session request should get an answer from the worker, and /test should get Cloudflare's HTTP 403 block page.

HTTPS Enforcement

The worker automatically redirects HTTP requests to HTTPS using a 301 redirect. This applies to all requests where the hostname includes the configured base_domain, except those on localhost (for local development with wrangler dev).

Best Practices

  • Set a unique token on each HTTP context that receives traffic from the public internet.
  • Use session instead of token when the sender's code is public, so a token copied from that code can't be used to post.
  • Use allowed_from wildcards on email contexts to restrict senders to expected domains.
  • Disable show_response_output in production to minimize information exposure.
  • Disable show_visitor_info unless you need IP and location details in notifications.
  • Add the block rule so requests to paths the proxy doesn't serve stop at Cloudflare.
  • On Pro plans and above, set up a Super Bot Fight Mode skip rule rather than disabling bot protection entirely.
  • Use error_topic only with ntfy servers you control — error notifications include full context details, request metadata, and email content as unmasked JSON attachments.