MQTT Push Notifications

Updated on September 05, 2026 Git Repository

Forward subscribed MQTT topics to Signalgrid push notifications
to receive broker events instantly on your iPhone, Android, and web devices.

Get started with Signalgrid Explore our API

mqtt2push is a small open source Go bridge that connects to an MQTT broker, subscribes to one or more MQTT topics, and forwards each received message to Signalgrid as a push notification.

If you are looking for MQTT push notifications, MQTT alerts to phone, MQTT notifications for iPhone or Android, or a simple MQTT to push gateway for Mosquitto, Home Assistant, or custom IoT systems, this integration is built for exactly that job.

This is useful for homelab alerts, IoT events, automation workflows, broker-based status updates, machine alarms, Home Assistant side-projects, and any other setup where MQTT already acts as your event bus.

What mqtt2push Does

  • Subscribes to one or more MQTT topics
  • Supports normal MQTT wildcards such as alerts/# and servers/+/status
  • Forwards MQTT payloads as Signalgrid push notifications
  • Uses the MQTT topic as the notification title
  • Works with plain MQTT and MQTT over TLS
  • Supports custom CA certificates, reconnects automatically, and re-subscribes after reconnect

Prerequisites

  • A running MQTT broker such as Mosquitto, EMQX, HiveMQ, or another MQTT-compatible server
  • A machine that can reach your broker and https://api.signalgrid.co
  • A Signalgrid account
  • Your Signalgrid client_key
  • Your Signalgrid channel token
  • Go installed if you want to build the bridge from source

Installation

Bash
# Clone the repository git clone https://github.com/signalgridco/mqtt2push.git # Enter the project directory cd mqtt2push # Build the binary go mod tidy go build -o mqtt2push .

The bridge reads its configuration from a config.yml file located next to the executable. This makes it easy to deploy as a lightweight MQTT notifier, MQTT alert forwarder, or background MQTT daemon on a VPS, homelab box, Raspberry Pi, or Docker host.

Minimal Configuration

A basic setup with one broker, one topic, and one Signalgrid target can look like this:

YAML
mqtt: broker: mqtt.example.com port: 1883 topics: - alerts/# - servers/+/status username: mqttuser password: mqttpassword qos: 0 client_id: mqtt2push tls: enabled: false signalgrid: client_key: YOUR_CLIENT_KEY channel: YOUR_CHANNEL type: INFO

If port is omitted, 1883 is used automatically for plain MQTT. MQTT QoS 0, 1, and 2 are supported.

Configuration Fields

Field
Description
mqtt.broker
MQTT broker hostname or IP address, for example mqtt.example.com
mqtt.port
MQTT broker port. When omitted, mqtt2push uses 1883 for plain MQTT and 8883 when TLS is enabled
mqtt.client_id
Client identifier used when the bridge connects to the broker
mqtt.username
MQTT username, if your broker requires authentication
mqtt.password
MQTT password, if your broker requires authentication
mqtt.topics
List of MQTT topics that should trigger Signalgrid notifications. MQTT wildcards are supported, which makes this useful for MQTT topic alerts and MQTT notification routing across many devices
mqtt.qos
MQTT QoS level for subscriptions. The bridge supports QoS 0, 1, and 2
signalgrid.client_key
Your Signalgrid client key used to authenticate push requests
signalgrid.channel
The target Signalgrid channel token that receives forwarded MQTT messages
signalgrid.type
The Signalgrid notification type used for every forwarded message, for example INFO, WARN, SUCCESS, or CRIT

TLS Configuration

If your broker uses MQTT over TLS, enable the optional TLS block and provide the CA file when needed. This is useful for secure Mosquitto notifications, remote MQTT alerts over the internet, and internal brokers that use private certificate authorities.

YAML
mqtt: broker: mqtt.internal.example port: 8883 topics: - factory/alarms/# username: mqttuser password: mqttpassword qos: 1 client_id: mqtt2push tls: enabled: true ca_file: /etc/mqtt2push/company-ca.pem signalgrid: client_key: YOUR_CLIENT_KEY channel: YOUR_CHANNEL type: WARN

When TLS is enabled without a custom CA file, mqtt2push uses the operating system trust store. If port is omitted, 8883 is used automatically.

How Notifications Are Built

For each received MQTT message, the bridge creates one Signalgrid push notification. In other words, mqtt2push turns MQTT messages into mobile push alerts without requiring any inbound ports on your phone.

Signalgrid field
Source
title
Derived from the MQTT topic, with slashes reformatted for cleaner display. For example, factory/line1/alarm becomes a readable MQTT notification title
body
The raw MQTT payload as plain text. mqtt2push does not interpret or transform the payload before sending the push notification
channel
Taken from signalgrid.channel in your configuration
type
Taken from signalgrid.type in your configuration

Run the Bridge

After placing config.yml next to the compiled binary, start the bridge:

Bash
./mqtt2push

When the bridge starts successfully, it connects to the broker and subscribes to every configured topic. New messages on those topics are then forwarded to Signalgrid immediately, which makes this a simple way to get MQTT alerts on iPhone, MQTT alerts on Android, or MQTT notifications in your browser.

Common Use Cases

Use case
How mqtt2push helps
MQTT alerts for servers
Forward broker messages from monitoring scripts, health checks, or automation tools to mobile push notifications
Home Assistant MQTT notifications
Send events from Home Assistant automations or MQTT-connected devices to your phone through Signalgrid
Mosquitto push notifications
Use Mosquitto as the broker and let mqtt2push act as the bridge from MQTT topics to phone alerts
Industrial or IoT alarms
Forward machine alarms, sensor thresholds, and edge-device events from MQTT to instant push notifications

FAQ

Question
Answer
Can I send MQTT notifications to iPhone and Android?
Yes. mqtt2push forwards MQTT messages to Signalgrid, and Signalgrid delivers them as push notifications to iPhone, Android, and web clients.
Does mqtt2push support wildcard topics?
Yes. Standard MQTT wildcard patterns such as # and + are supported.
Can I use mqtt2push with Mosquitto?
Yes. Mosquitto is a common fit for this setup, but any MQTT-compatible broker should work.
Does the bridge modify MQTT payloads?
No. The payload is forwarded as the notification body, while the topic becomes the notification title.

Manual Testing

The quickest end-to-end test is to start the bridge, publish a message to one of the subscribed topics using your normal MQTT tooling, and then verify that a Signalgrid notification appears on the target devices.

If you do not receive anything, first verify your Signalgrid credentials with a direct API request from the same machine:

Bash
curl -X POST https://api.signalgrid.co/v1/push \ -d "client_key=YOUR_CLIENT_KEY" \ -d "channel=YOUR_CHANNEL_TOKEN" \ -d "title=MQTT bridge test" \ -d "body=Signalgrid API test succeeded" \ -d "type=INFO"

Troubleshooting

Issue
What to check
The bridge starts but no notifications arrive
Verify signalgrid.client_key, signalgrid.channel, and that your device is signed in to the same Signalgrid account
The bridge cannot connect to the broker
Check the broker URL, network reachability, username/password, and whether the port matches your MQTT or MQTT over TLS listener
TLS connections fail
Confirm mqtt.tls.enabled is set correctly and that mqtt.tls.ca_file points to the right CA certificate when your broker requires it
All notifications have the same severity
That is expected, because the bridge uses the static signalgrid.type value from your configuration for every forwarded message

See also

Push API mqtt2push on GitHub
Any questions? Contact support.
LLM? Read llms.txt.
Visit us on GitHub