Skip to main content

Interpreters Overview

Interpreters transform raw webhook payloads and email content into standardized ntfy notifications.

How Interpreters Work

When a request or email arrives, the pipeline invokes the context's configured interpreter. The interpreter receives the raw input (string, JSON object, or binary) and returns a result with a notification object (title, body, priority, tags, icon, actions, markdown) and an optional attachment at the same level (not inside the notification).

The filename field accompanies the attachment. The plain-text interpreter returns a binary request body as an attachment, while an error topic sends its diagnostic data as error-debug.json.

  • If an interpreter returns null, the notification is suppressed (useful for filtering duplicate or irrelevant events).
  • If interpretation fails, the pipeline returns HTTP 422 and optionally forwards the error to the context's error_topic.

HTML is automatically stripped from all notification bodies after interpretation.

Available Interpreters

InterpreterInput TypeBest For
plain-textAnyGeneric webhooks, simple text notifications, testing
ntfy-jsonJSONServices that can send structured ntfy-compatible payloads
statuspageJSONStatuspage.io incident and component update webhooks
synologyJSONSynology DSM webhook notifications
seerrJSONSeerr media request and issue notifications
transmission-vpnJSONTransmission VPN alerts, such as a dropped VPN or a finished torrent
pfsense-actionsJSONpfSense Actions alerts, such as pfSense going unreachable
discord-stonker-botJSONDiscord Stonker Bot alerts, such as a lost Discord connection
outpostJSONOutpost alerts, such as updated containers or a failed update
pfsenseEmailpfSense firewall notification emails
unifiEmailUniFi Network controller notification emails

Choosing an Interpreter

  • For services that send raw text or unstructured payloads, use plain-text.
  • For services where you control the payload format, use ntfy-json to send pre-formatted notifications with full control over title, priority, tags, and other fields.
  • For the specific services listed above, use the dedicated interpreter to get formatted titles, priority inference, and contextual tags.
  • If you need email-to-ntfy forwarding from pfSense or UniFi, use their respective interpreters with an email context.
  • For alerts from Transmission VPN, pfSense Actions, Discord Stonker Bot, or Outpost, use the interpreter named after the app, and choose ntfy-reverse-proxy as the destination's service on the app's Notifications page.

tip

If your webhook does not perfectly match the expected shape, try the dedicated interpreter first — most have lenient parsing. If it fails with 422, fall back to plain-text to see the raw payload, then consider ntfy-json if you can normalize the format on the source side.

Notification Suppression

Most interpreters always return a notification. Statuspage can return null, which suppresses the notification:

  • statuspage — Component-only updates without an incident and incident updates already sent (detected through KV).

Malformed JSON is not suppression: statuspage and ntfy-json both fail with HTTP 422, allowing the configured error topic to report the problem. See Statuspage and ntfy JSON for details.

Interpreter Availability by Context Type

The interactive CLI menu filters the interpreter list based on context type:

  • HTTP contexts — plain-text, ntfy-json, seerr, synology, statuspage, transmission-vpn, pfsense-actions, discord-stonker-bot, outpost
  • Email contexts — plain-text, pfsense, unifi

info

The config schema allows any of the 11 interpreters for either type, so you can assign any interpreter to any context via direct config editing.