HTTP integration

TBMQ HTTP Integration forwards MQTT messages from devices to an external system using the HTTP protocol. It acts as a bridge between TBMQ and external applications, ensuring reliable data exchange.

1. Device (client) publishes an MQTT message to a topic matching the integration’s topic filters.
2. TBMQ broker receives the message and forwards it to the TBMQ Integration Executor.
3. Integration Executor processes the message, formats it as an HTTP request, and forwards it to the external service.
4. External service receives the request and processes the data.

• A running TBMQ instance.
• An external service ready to receive HTTP requests (e.g., ThingsBoard Cloud).
• A client capable of publishing MQTT messages (e.g., TBMQ WebSocket Client).

In this tutorial, ThingsBoard is used as the external HTTP service. Any other HTTP-compatible service can be used instead.

Follow the ThingsBoard HTTP Integration Guide to create an integration on ThingsBoard Cloud.

Once created:

1. Open the details page and enable debug mode to verify data reception.
2. Copy the HTTP endpoint URL — you will need it in the next step.

1. Go to the Integrations page and click the ”+” button.
2. Select HTTP as the integration type and click Next.
3. On the Topic Filters step, click Next to subscribe to the default topic tbmq/#.
4. In the Configuration step, paste the Endpoint URL from the ThingsBoard Integration.
5. Open Advanced settings and set Payload content type to JSON.
6. Click Add to save the integration.

Navigate to Integrations page and click the plus icon Select HTTP as the integration type and click Next Click Next to subscribe to default topic tbmq/# Paste the Endpoint URL from ThingsBoard Open Advanced settings, set Payload content type to JSON, and click Add

Topic filters define MQTT-based subscriptions that trigger the integration. When TBMQ receives a message matching a configured topic filter, the integration processes it and forwards the data to the external system.

For example, with the topic filter tbmq/devices/+/status, any of the following messages will trigger the integration:

tbmq/devices/device-01/status
tbmq/devices/gateway-01/status

TBMQ logs integration-related events for debugging and troubleshooting:

• Lifecycle Events — logs events such as Started, Created, Updated, Stopped.
• Statistics — insights into integration performance, including processed message counts and error rates.
• Errors — captures failures related to authentication, timeouts, payload formatting, or connectivity issues.

Lifecycle events for the HTTP integration Statistics events showing processed message counts Error events capturing integration failures

1. Navigate to the WebSocket Client page.
2. Select WebSocket Default Connection (or any working connection) and click Connect. Verify the connection status shows Connected.
3. Set the Topic field to tbmq/http-integration to match the integration’s topic filter tbmq/#.
4. Click the Send icon to publish the message.

Select a working connection and click Connect Set topic to tbmq/http-integration and click Send

If successful, open ThingsBoard Cloud → HTTP Integration details → Events tab. You should see an event with status OK and a payload similar to:

{
    "payload": {
        "temperature": 25
    },
    "topicName": "tbmq/http-integration",
    "clientId": "tbmq_7QUvZzow",
    "eventType": "PUBLISH_MSG",
    "qos": 1,
    "retain": false,
    "tbmqIeNode": "tbmq_ie_node",
    "tbmqNode": "tbmq_node",
    "ts": 1742553324248,
    "props": {},
    "metadata": {
        "integrationName": "HTTP integration"
    }
}

Open ThingsBoard Cloud HTTP integration details Events tab showing the message received from TBMQ HTTP integration

Message field descriptions: