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, version 2.1 or later, with the TBMQ Integration Executor service running. Without a reachable executor, saving an integration fails with a validation timeout.
• An external service ready to receive HTTP requests (e.g., ThingsBoard Cloud).
• A client capable of publishing MQTT messages (e.g., TBMQ WebSocket Client).

This step happens on the receiving side, not in TBMQ. This tutorial uses ThingsBoard as the external HTTP service; any other HTTP-compatible service works the same way, and if you already have an endpoint URL you can skip ahead to creating the TBMQ integration.

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 Filters and events step, keep the default Topic filters entry tbmq/#, leave Lifecycle events empty, and click Next.
4. In the Configuration step, paste the Endpoint URL you copied above.
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.

Topic filters are optional if you select at least one lifecycle event type instead — an integration only has to have one of the two.

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

Send only message payload decides whether the endpoint receives the bare payload or the full envelope, and Payload content type decides how the payload itself is encoded:

A client lifecycle event never goes through this: it has no MQTT payload to encode and is always sent as its own JSON object.

Besides the messages matched by topic filters, this integration can deliver client lifecycle events — a client connecting, disconnecting, changing its subscriptions, or failing authentication or authorization.

Pick the event types on the Filters and events step while creating the integration, or add them later:

1. Open the integration on the Integrations page and click the Toggle edit mode button (pencil icon).
2. Click the Lifecycle events field to list the available event types, then select the ones you need: Client connected, Client disconnected, Client subscribed, Client unsubscribed, Client authentication failed, Client authorization failed, Client connection failed. Each one is added as a chip; remove it with its x.
3. Click Apply changes.

Events are sent to the same Endpoint URL as messages, as a JSON request body. Send only message payload, Payload content type, and Send as binary on parsing error apply to message payloads only — an event is always delivered as JSON.

These are the integration’s own events, recorded inside TBMQ for debugging and troubleshooting. They are not the client lifecycle events described above: those are about MQTT clients and are delivered to your HTTP endpoint, while these describe the integration itself and never leave TBMQ.

• 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. Leave the pre-filled Payload {"temperature": 25} as is — it is what the endpoint receives below.
5. 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: