Skip to main content
All CollectionsGetting startedOnomondo app featuresWebhooks
How to set up a webhook to receive SMS from device and send an automated SMS response with the API

How to set up a webhook to receive SMS from device and send an automated SMS response with the API

Devices sending SMS must use Onomondo’s secure platform/API. Use Webhooks to catch SMS if you're not on the platform.

Jakub Kubinski avatar
Written by Jakub Kubinski
Updated over a week ago

Before you start

You will need to find a third-party app connection service or build your own HTTPS server endpoint to connect the webhook event sent by Onomondo to the notification service you choose. Some common app connection services are:

Before starting, it will also be good to understand the basics of using webhooks and SMS through the Onomondo Network:

SMS to the device can only be sent via the Onomondo app or the API.

Test setup

The example in this article will look at capturing SMS sent by the device outside of the Onomondo app and automating an SMS response.

There are a few practical use cases to consider here. For instance, some devices have the option to configure APN settings via SMS. For the sake of this guide, we will adopt this scenario and set up a custom service to respond to the same number as provided when the SMS is received without reprogramming the device.

This example uses Make. It has a free version that includes the webhook service and gives you more options on how the notification is displayed in the service of your choice.

A simple way to set up the test is by using the SMS feature on a mobile phone with an Onomondo SIM. Once the automation is set up, you can test and configure further using your dedicated IoT devices.

It is also important to add a tag to the SIM you are testing with, as this feature is becomes crucial in limiting webhooks to a given subset of SIMs. During development, you might want to limit the SMS webhooks to your test device only.

In production, tags can also be used to have different endpoints / webhooks for different products / customers, allowing you to effectively customize your setup.

In this example, the SIM will use a tag we have created called 'GlobalTrackerUnit'.

Checklist

To perform the following test yourself, using this exact method, you will need:

  1. A mobile phone with an Onomondo SIM.

  2. A free account on Make.com.

  3. Admin or Owner level permissions in the Onomondo app.

  4. A custom tag for testing purposes.

The simple scenario

We will use Make's scenarios feature to set up an automation that captures the SMS webhook sent by Onomondo and responds to the SMS whenever the device tries to communicate.

Step 1: Setting up a scenario in Make

There is some initial set up required. In order to get started, you will have to do a few things:

  1. Create a new Make account, unless you have one already.

  2. Go to "Scenarios" tab and click on "+ Create a new scenario".

  3. Click on the initial module, and select "Custom webhook" (found under "Webhooks").

  4. Next, click on "Create a new webhook" and give it a name. In the example we use 'smsFromDevice'. You can leave the other field(s) blank.

  5. The application will generate an endpoint URL. Copy the URL. You will need it later.
    ​

Step 2: Creating a webhook in the Onomondo app

Webhooks are a management feature and can only be created by Admin and Owner level users. You can larn more about user access permissions here.

Once you have obtained the webhook URL from Make:

  1. Create a webhook in the Onomondo app. Go to the Webhooks tab in the and click the "New webhook" button.


    ​

  2. Give the webhook a unique name.

  3. Paste the URL.

  4. Assign the tag to the webhook.

    • Select that tag under the "Limit to" field. In this example, we restrict the webhook to send only events related to the Tag 'GlobalTrackerUnit'.

    • If you do not specify this, you will be capturing webhook events from all SIMs.

    • Make sure that the same tag is assigned to the test SIM.

  5. Activate the webhook. Simply tick on "Active".

  6. Choose the events. Here, you can pick all events you interested in monitoring with this webhook, corresponding to a specific set of SIMs.

    • In this example, we are only interested in "SMS" type. Select "SMS" and deselect all other types of events.

  7. Save it. Cick the "Create Webhook" button at the bottom right of the page.
    ​

Ensure you select ‘SMS’ and not ‘SMS Usage’, as only ‘SMS’ will provide the actual SMS content being sent from the device.

Here is how the settings should look like once you are done:

Step 3: Capturing the SMS webhook in Make

Once the webhook is set up in the Onomondo app, you're ready to move on to testing.

  1. Go online. Turn on the mobile phone and make sure it's attached to one of the local networks. Verify the SIM status and whether you see "Attached GSM connection" in the Network Logs.


    ​

  2. Run the scenario. Go back to Scenario setup in Make and click the "Run once" button. Leave it running.

  3. Send an SMS from your mobile phone.

    • It does not matter which phone number the SMS is addressed to, but we recommend using an international prefix. This is how Onomondo receives it in our SMS server and how it appears in the webhook event.

    • In this example, we are sending a message: "GetAPN" to +45123456789.​

  4. Inspect the result in Make. In Make, you will see a bubble pop up from the Webhooks module. You can click on it to get a breakdown of the data received by the Webhook module. The Webhook module uses this initial packet to identify the data structure it will expect in the future.

    ​

Congratulations, you have just captured the SMS webhook in real time!
​

No webhook received?

If you do not see a response come through to Make, check the Error Logs in the Onomondo app. This will show you the most recent errors for Onomondo Webhooks and Connectors. This might help with debugging.

As you can see in the above example:

  • the phone number to which the SMS was addressed (+45123456789) becomes the 'to' field in the SMS event.

  • the body of the SMS ("GetAPN") becomes the 'text'.

  • you will also see the SIM ID and other information displayed.

How you set up the remaining automation will depend on your specific use case. As mentioned already, this example will demonstrate how to automatically send responses based on SMS a device sends.

Only want notifications?

If you want an example of receiving notifications when a SMS is received, try adapting the Usage Alerts example using a webhook with SMS events.

Step 4: Creating a JSON object for the SMS response

Now, it's time to set up a custom response to the "GetAPN" text message. The desired reponse is "onomondo".

As the response body will contain text in a JSON format, we can keep it simple by using the ‘Create JSON’ module.

Here is how to do it:

  1. Go back to your scenario in Make.

  2. Add JSON module. Click on 'Add another module' next to the webhook and select 'Create JSON' from the list. This is a transformer module that will enable you to ensure correct formatting.

  3. Set the data structure of the JSON response.

    • Click the 'Add' button

    • Give it a unique name, fx. "sendSMS".

    • Add two new items:

      • Name: from, Type: text

      • Name: text, Type: text

    • Save

  4. Fill out the fields.

    • The 'from' field can be reused from the data structure. Select "to".

    • The text field should contain: "onomondo" (the APN name)
      ​

  5. Save.

Step 5: Sending the SMS using Onomondo's API

For specific information on how to send SMS with the Onomondo API, take a look at the API documentation and a dedicated guide.

Now, let's continue with the automation and so that the Onomondo API can respond to the text message correctly.

  1. Go to the Onomondo app. Find the SIM in the dashboard or the SIMs tab.

  2. Confirm the tag is set. Make sure the SIM you are testing is paired with the right tag. In this example, the tag is "GlobalTrackerUnit".

  3. Enable write access. Go to Tags tab, edit tag, and enable "write access" on the tag you are using. Otherwise, you will only be limited to GET API requests, and you won't be able to POST SMS.

  4. Create an API key.

    • Make sure to save your API Key securely.

    • You will only see the API Key once!

    • Pair the API key with the same tag as the webhook - "GlobalTrackerUnit" (optional, but recommended).

  5. Create a response. Go to scenario setup in Make and add an HTTP module. Choose "Make a request" action from the list.

  6. Set the following parameters:

    • URL: https://api.onomondo.com/sms/sim_id

    • Method: POST

    • Headers

      • Name: Authorization

      • Value: YOUR_API_KEY

    • Body tape: Raw

    • Content type: JSON (application/json)

    • Request content: JSON string (this will correspond to the text defined in the previous module)

  7. Click "Save".

Step 6: Test sending the SMS response

  1. Run it. Once you have set up the HTTP module, save the Scenario and click 'Run Once'.

  2. Send an SMS from your mobile phone.

    • Neither the number, nor the content of the SMS matters in this case, as the API will respond the same way to the webhook.

    • For the sake of this example, we will send a "GetAPN" message to +45123456789.

  3. Monitor response. Once the SMS is sent, you should get an SMS response: "onomondo" sent back to your phone.

    • This will also be visible in the SMS console in the Onomondo app.

    • In Make, bubbles will pop up next to all modules showing the input and output of each of them. If you open any of those, you will see more details.

Now your device can send SMS and receive an automated response, based on the webhook.

No logic built in

At this stage, any SMS sent by the device will always trigger the same response, defined by the JSON module. Any SMS from a device will respond the same way.

Adding extra logic to the scenario

There are a couple of ways of adding logic to the above scenario. Sometimes, you may want to create different actions depending on what the device is asking for (via SMS). The most basic example is to use an if statement in the JSON Module to change the text response based on the SMS from the device.

To do this you can use another Make feature called the "Router" module.

Step 7: Setting up different cases

In this example, we are going to show how to use a "Router" module to set up the scenario to only send the APN if a specific request comes from the device, followed by a catch-all statement to send an email notification if another SMS is sent to the device.

This scenario is designed so that:

  • If the device sends SMS "GetAPN" - respond with "onomondo".

  • If the device sends any other SMS - notify me via email.

  1. Go down to the green 'Flow control' button and select the Router module.
    ​

  2. Next, you will need to disconnect the existing flow between the Webhooks and JSON modules and insert the Router in between it.
    ​

  3. Add a filter on the link between the Router and JSON module (the one linked with the API request).

    • Give it a label that will help you identify the purpose of the filter, fx. "APN".

    • Set the condition for the ‘text’ field in the webhook event to match the SMS command the device sends to request an APN. In this example, we are using "GetAPN" as a trigger.
      ​

  4. Afterwards, add a filter to the second flow out of the Router module. First, label it, fx. "Unknown SMS command". Then, click the checkbox under the label field to enable the fallback route. This is instead of setting another condition.

At this point, the setup should look like this:

Step 8: Adding an email notification to the scenario

The final step for adding a fallback is to create a notification of your choice. In this example, the Gmail module was selected, but there are many other options, including generic email, Slack, Microsoft Teams, and more, depending on your preference.

  1. Add a "Gmail" module to the fallback route.

  2. Define the parameters. Consider reusing webhook parameters from the previous module:

    • Email recipient

    • Subject (fx. "Device with SIM sim_id sent a text")

    • Content (fx. "Here is the message: text")

  3. Link it with your inbox. Click "Create a connection" and sign into Gmail. This is specific to this integration.

  4. Save it.

According to this scenario, whenever your device asks for an APN, Onomondo API will respond with the right APN name. If the device sends any other text, you will be notified via email and can respond to it either directly from the Onomondo app or the API.

Step 9: Adding more steps

Once this is set up, you can add more steps based on what is already programmed into your devices. If you are developing your firmware, you can determine what functionalities to build into it using SMS.
​

A simple way to add new routes to the Scenario is to click the plus sign in the Router module, copy the JSON/HTTP modules from the previous example, modify them as needed, and set a new filter.

You can also add different steps/API calls to the flow if you want to pull different information from different parts of Onomondo or other Services/API calls that are valuable.

Preparing for production

Once you have set up the logic as desired, save it and turn the Scenario on. Select ‘Immediately’ so that the Scenario runs whenever an event is received, instead of at specific intervals.

Once it is online, run a few extra tests with different SMS commands you have set up, and test it with one of your devices by adding the tag used for development.

Congratulations, you have now set up an SMS server for your devices.

Don’t forget to update the tag once you move on from development to production, and make sure it's assigned correctly to both the webhook and the API key you created.

Wrapping up

Capturing webhooks outside of the Onomondo app offers a great way of monitoring your fleet and taking action upon different SIM events.

In this guide, we covered a practical use case, where 3rd party integrations can help you capture SMS sent by the device and program SMS responses to be sent via the Onomondo API.

We hope that you will find utility in SMS webhooks. In case you are wondering about different webhook events and their practical use cases, check out this article next:

Note on SMS in IoT

SMS can serve as a reliable backup communication method when the device fails to connect to data but still connects to GSM. For example, you can add logic to the device to restart itself or its module upon receiving a specific SMS. However, depending on your device setup, SMS may not be the most efficient or cost-effective communication method. Instead, consider taking a look at the ability to send packets to the device using Messages API call.

Did this answer your question?