Publishing to Thingstream MQTT topics over HTTP

Prerequisites

You'll need an active, IP thing in your Thingstream domain in order to authenticate and send messages using Webhooks.

You will also need a version of Chrome or Firefox browser on an internet enabled device or access to a terminal window on an internet ready device that has curl enabled.

HTTP Publish Using CURL

If you are intending to use CURL from a Windows 10 environment, it is recommended you install the Windows Subsystem for Linux and use the Linux terminal/shell . Instruction for this are available here.

1. Sign into your domain on the Thingstream portal and navigate to the Things List.

2. Ensure that you have an active IP thing in your list.

3. Select the IP thing and go to the Credentials tab of the Thing Details pane.

4. Scroll down to Webhooks:

   • Enable Webhooks if you haven't already and you will see a Username, Password and Curl example for your currently selected device.

   • Click on the Curl string to copy it to the clipboard.

5. Navigate to a Terminal window, paste the CURL string into the terminal window and press enter.

6. The Curl string will look something like this:

curl -H "Content-Type: application/octet-stream" -H "Publish-QoS: 0" --user "<username>:<password>" --request POST "https://webhook.thingstream.io/hook/my-first-topic" -d "this is a webhook publish" <username> and <password> will be pre-filled with your devices credentials

The URL includes a Topic path 'my-first-topic' and a message 'this is a webhook publish'. These can be modified to a topic and message of your choice.

HTTP Publish Using Firefox

Step 1: Install the RESTClient Firefox Add-on.

1. To install the RESTClient Firefox Add-on, go to the RESTClient Add-on page on the Firefox Add-ons Store.

2. Click the Add to Firefox button to install the RESTClient App. The download should take a few minutes depending on your internet connection.

Step 2: Add the request method and URL

1. Once you've downloaded the app you can launch RESTClient. follow instruction to Migrate from RESTClient 2 if you wish to save the details you are about to enter in preferences.

2. Use the Method dropdown to change the request method from GET to POST.

3. Find your IP thing in the Thingstream portal, and find the Webhooks CURL example from the Credentials tab of the Thing Details pane. Extract the HTTPS URL from the CURL example: https://webhook.thingstream.io/hook/my-first-topic

4. Enter this HTTPS URL into the URL field, replacing my-first-topic with a topic of your choosing.

Step 3: Basic Authentication

1. In the RESTClient navigation bar go to Authentication > Basic Authentication.

2. In the Basic Authentication modal:

   • Enter the Username and Password of your IP thing.

   • Click Okay.

You will know this was successful when you see a Basic authentication lozenge next to the Request section title.

Step 4: Set the Content-Type Header

1. In the RESTClient navigation bar go to Headers > Custom Header.

2. In the Request Headers modal:

   • Enter Name: 'Content-Type'.

   • Enter Attribute Value: 'application/octet-stream'.

3. Click Okay.

This will result in a Header tag appearing in the Headers section of RESTClient.

Step 5: Set the Publish-QoS Header

We now repeat the process to set the Publish-QoS Header

1. In the RESTClient navigation bar go to Headers > Custom Header.

2. In the Request Headers modal:

   • Enter Name: 'Publish-QoS'.

   • Enter Attribute Value: '0'.

3. Click Okay.

This will result in a second Header tag appearing in the Headers section of RESTClient.

Step 6: Provide a message

1. Enter your message into the Body Editor.

2. Click Send

To Confirm a successful POST, RESTClient will populate the Response section. This should include a response status code of 200 OK. If you have a flow listening to your specified topic, it should be actioned.

HTTP Publish Using Chrome

NOTE: The Postman Chrome App will soon be deprecated in favour of a native app.

Step 1: Install the Postman Chrome Add-on

1. To install the Postman Chrome App, go to the Postman Add-on page on the Google Chrome Web store.

2. Click the Add to Chrome button to install the Postman App. The download should take a few minutes depending on your internet connection.

Step 2: Create a new Postman collection

1. Once you've downloaded the app you can launch Postman. You may be prompted to sign up.

2. The Create New Tab appears by default. In the Create New Tab, click Collection to create a new collection to house our POST request.

3. In the Create New Collection modal:

   • Enter a name and optional description.

4. Click the Create button

After you save the request, you can add the method, URL, headers, and body to the request in the builder.

Step 3: Add the request method and URL

1. Use the control dropdown to change the request method from GET to POST.

2. Find your IP thing in the Thingstream portal, and find the Webhooks CURL example from the Credentials tab of the Thing Details pane. Extract the HTTPS URL from the CURL example: https://webhook.thingstream.io/hook/my-first-topic

3. Enter this HTTPS URL into the URL field, replacing my-first-topic with a topic of your choosing.

Step 4: Authenticate the POST

1. In the Authorization tab, select Basic Auth from the TYPE drop down menu.

2. To set the authorization parameters for a request:

   • Take the Username and Password of your IP thing and paste them into the fields in the Authorization tab .

3. Click the Update Request button. You will see a new header entry created for you on the headers toggle.

Step 5: Set the Headers

Clicking on the headers toggle will show the headers key-value editor. Headers in Postman are Key Value pairs.

1. Click the Headers toggle.

2. The first Key we will enter is "Content-Type" it's corresponding Value will be "application/octet-stream".

3. We now repeat the process this time the Key will be "Publish-QoS" and the Value will be "0".

We now have all required headers and can provide a message using the Request Body.

Step 6: Provide a message

1. Click on the Body tab and select RAW (The default is text).

2. Enter your message into the Body Editor

3. Click Send

This should result in a message indicating Status 200 OK. If you have a flow listening to your specified topic, it should be actioned.