MQTT

https://shoutrrr.nickfedor.com/services/push/mqtt/

URL Format

The MQTT service supports two URL schemes for connection security:

• mqtt://: Standard unencrypted connection (port 1883 by default)
• mqtts://: TLS-encrypted connection (port 8883 by default)

mqtt://[username[:password]@]host[:port]/topic

mqtts://[username[:password]@]host[:port]/topic

URL Fields

• Username - Auth username
  Default: empty
  URL part: mqtt://username:password@host:port/topic

• Password - Auth password
  Default: empty
  URL part: mqtt://username:password@host:port/topic

• Host - MQTT broker hostname
  Default: localhost
  URL part: mqtt://username:password@host:port/topic

• Port - MQTT broker port
  Default: 1883 (mqtt) or 8883 (mqtts)
  URL part: mqtt://username:password@host:port/topic

• Topic - Target topic name (Required)
  URL part: mqtt://username:password@host:port/topic

Query Parameters

• CleanSession - Start with a clean session
  Default: ✔ yes

• ClientID - MQTT client identifier
  Default: shoutrrr

• DisableTLS - Disable TLS encryption
  Default: ❌ no

• DisableTLSVerification - Disable TLS certificate verification (useful for self-signed certificates)
  Default: ❌ no

• QoS - Quality of Service level (0, 1, or 2)
  Default: 0
  Possible values: 0 (AtMostOnce), 1 (AtLeastOnce), 2 (ExactlyOnce)

TLS Configuration Options

The following options control TLS behavior:

• disabletls: When set to yes, forces an unencrypted connection even if the mqtts:// scheme is used. This overrides the scheme's implicit TLS requirement.
• disabletlsverification: When set to yes, disables TLS certificate verification while still using encryption. This is useful for self-signed certificates.

Security Warning: Silent TLS Downgrade

Setting disabletls=yes with mqtts:// will force an unencrypted connection despite the secure scheme. This is likely unexpected behavior and can cause silent downgrades where you believe traffic is encrypted but it is not.

Recommendation: If you intentionally want an unencrypted connection, use mqtt:// (non-TLS scheme) instead of combining mqtts:// with disabletls=yes.

When to Use disabletls=yes

This option is intended for specific edge cases, such as:

• TLS-terminating proxy: When connecting through a proxy that handles TLS termination, where the connection from client-to-proxy uses TLS but proxy-to-broker is plain MQTT. For example, a reverse proxy like Traefik or nginx that terminates TLS and forwards to an internal MQTT broker.
• Testing environments: Local development where encryption is not required.

Examples

Basic Notification

mqtt://broker.example.com/notifications

With Authentication

mqtt://user:[email protected]:1883/home/alerts

Secure Connection

mqtts://user:[email protected]:8883/home/alerts

Home Assistant

mqtt://homeassistant.local:1883/homeassistant/notification

Mosquitto broker with custom client ID

mqtt://mosquitto.example.com:1883/sensors/alerts?clientid=shoutrrr-alerts&qos=2

Self-signed Certificate

mqtts://broker.local:8883/secure/alerts?disabletlsverification=yes

Full Configuration

mqtts://admin:[email protected]:8883/production/alerts?clientid=prod-shoutrrr&qos=1&retained=yes&cleansession=no