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. TheBearerprefix is case-sensitive (lowercasebearerwill not match).Authorization: {token}— A raw token without theBearerprefix.
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.
{
"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
- The sender sends a
POSTorPUTtohttps://{id}.ntfy.example.com/session. - The worker replies with a signed session token.
- The sender posts its message with
Authorization: Bearer {token}from the same IP address. - 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.
{
"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_hourtokens per hour, which defaults to 10. Further/sessionrequests 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
deploycreates. Without it,/sessionreturns 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 headerInvalid session tokenExpired session tokenSession token was issued to another addressSession token was already usedSession 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
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.comallows only that address. - Wildcard —
*@example.comallows 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.
{
"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, andallowed_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_notewhen 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.
- 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.
- 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.
- If:
- 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.
- Open Dashboard > your domain > Security > Security rules and select Create rule > Custom rules.
- Name the rule, for example
Reverse Proxy for ntfy. - Select Edit expression and paste the expression below. Replace
ntfy.example.comwith yourbase_domain. - Set Choose action to Block.
- Set Select order to First, then select Deploy.
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.phpor/.env. - Query strings — Any URL with
?parameters, which no sender needs. next-actionheader — 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
tokenon each HTTP context that receives traffic from the public internet. - Use
sessioninstead oftokenwhen the sender's code is public, so a token copied from that code can't be used to post. - Use
allowed_fromwildcards on email contexts to restrict senders to expected domains. - Disable
show_response_outputin production to minimize information exposure. - Disable
show_visitor_infounless 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_topiconly with ntfy servers you control — error notifications include full context details, request metadata, and email content as unmasked JSON attachments.