Introduction
Webhooks are an essential part of modern web development and are key to tailoring solutions.
Our tool enables you to build webhooks, i.e. information flows that allow you to receive real-time events at a URL endpoint based on your specific use case.
Webhooks vs. API Polling: A Proactive Approach
Webhooks offer a proactive way of receiving data. Rather than manually polling Onomondo’s API or refreshing the app to check for updates, webhooks automatically deliver data on connectivity events to your system the moment something happens.
Think of it like this:
API polling is like asking over and over: “Has anything changed yet?”
Webhooks are like getting a tap on the shoulder: “Something just changed—here’s the update.”
So instead of wondering, “Has my device connected yet?”, Onomondo simply notifies you the instant it does. You can decide how to ingest that data and how to act upon it.
Onomondo webhooks are free to set up and free to use within every Onomondo subscription plan. There are no extra charges related to webhook usage.
Webhook events
There are eight types of webhook events and it is up to you if you want to create a Webhook for a subsection of these events, or all of them.
Let's break down different types of events supported by Onomondo and how they can help you with your fleet management.
Network authentication
This event occurs whenever the device has asked to attach to the network. This is the first part of a connection sequence.
Benefits:
Early visibility into a device's connectivity attempts, even before it's fully registered.
Useful for diagnosing connectivity issues—e.g., failed attachment due to SIM restrictions, roaming agreements, or signal issues.
Helps track roaming behavior, especially in multi-network environments.
Example:
{
"type": "network-authentication",
"id": "093e8507-d3dd-4599-84f0-f3159c32f1c9",
"sim_id": "000000001",
"sim_label": "valid-example",
"time": "2025-04-09T12:23:26.533Z",
"iccid": "8945738730000000012",
"status": null,
"imei": "123456789123456",
"reason": null,
"network_type": "4G",
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
}
}
If:
"status": null,
"reason": null
then the network authentication was successful.
If the object contains different values, you might have to investigate what went wrong with signaling logs.
Network registration
This event occurs whenever the device has attached to (or "registered with") the network and whenever the device has attached data connection (opened a data tunnel) with the Onomondo packet gateway.
This would correspond to either:
"Attached GSM / 2G / 3G / 4G connection on network..."
or
"Attached data connection on network..."
as seen in the Network Logs.
Benefits:
Confirms that a device is online and capable of communication.
Enables real-time monitoring of connectivity status.
Can be correlated with usage or location data to build a full picture of device activity.
Example:
{
"id": "c2cd019f-5d5f-42d4-8e7c-a7213da271b8",
"time": "2025-04-09T12:23:26.559Z",
"type": "network-registration",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"network_type": "4G",
"imei": "123456789123456",
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
},
"sim_label": "valid-example"
}
Network deregistration
This event occurs whenever the device has detached data connection from the network. Once this happens, the device has closed the data session and gone offline. The webhook object provides information about the size of the session payload as well.
Benefits:
Enables session tracking, e.g., how long a device stays connected.
Indicates a device has gone offline or moved out of coverage (unless a new registration follows right afterwards).
Useful for detecting power cycles, device shutdowns, or signal loss.
Example:
{
"type": "network-deregistration",
"id": "147abfe0-5609-4b03-96d8-af88b9650638",
"session_id": "97a525e4-b11b-414b-b125-c0d96591fbcf",
"time": "2025-04-09T13:41:02.815Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"imei": "123456789123456",
"network_type": "4G",
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
},
"ipv4": "123.01.23.012",
"session_usage": {
"upload": 123,
"download": 5555
},
"sim_label": "valid-example"
}
Location update
This event displays the approximate location of the last cell tower the device attached to, sent every time the device connects to a new cell.
Benefits:
Gives approximate location tracking even without GPS.
Useful for debugging connectivity issues by geography.
Enables geo-based analytics.
Example:
{
"type": "location",
"ipv4": "100.70.24.198",
"imei": "123456789123456",
"time": "2025-04-09T12:11:59.601Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"location": {
"location_area_code": 1111,
"cell_id": 9706,
"accuracy": 769,
"lat": 55.6627488,
"lng": 12.5784532
},
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
},
"session_id": "9b2b067e-99cd-4b82-925b-0718b615ee13",
"sim_label": "valid-example"
}
Data usage
This event displays usage records per SIM, updated every 15 minutes of activity or when a SIM deregisters from a network and closes a data session (whichever occurs first).
Benefits:
Enables near real-time usage tracking for each SIM.
Facilitates cost control and usage optimization.
Supports alerting for abnormal patterns (e.g., sudden spikes in usage).
Example:
{
"type": "usage",
"id": "d08592fd-823e-3d4d-af99-1509a7220fb4",
"session_id": "0afcd0cd-3119-3b6b-a7c2-dc6a9fe1f414",
"time": "2020-04-23T11:39:01.000Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"ipv4": "123.01.23.012",
"imei": "123456789123456"
"bytes": 9484,
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
},
"sim_label": "valid-example",
}
Usage alert
This event occurs whenever a device reaches a usage alert threshold (optional) or is blocked by usage limit. The event object will also display the reason, either as "alert-threshold" or "blocked".
Benefits:
Delivers proactive alerts to prevent bill shocks or overuse.
Can trigger automated responses (e.g., notify users, shut down services).
Helps enforce business rules or SLA limits per device/SIM.
Example (alert threshold reached):
{
"type": "usage-alert",
"reason": "alert-threshold",
"time": "2025-04-10T10:08:36.530Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"ipv4": "123.01.23.012",
"data_limit": {
"used": 1101976,
"total": 2000000,
"type": "monthly",
"period": "202112",
"alert_threshold": 1000000,
"resets_at": "2025-05-01T00:00:00.000Z"
},
"sim_label": "valid-example"
}
Example (usage limit reached):
{
"type": "usage-alert",
"reason": "blocked",
"time": "2025-04-10T10:09:41.571Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"ipv4": "123.01.23.012",
"data_limit": {
"used": 1934264,
"total": 2000000,
"type": "monthly",
"period": "202112",
"alert_threshold": 1000000,
"resets_at": "2025-05-01T00:00:00.000Z"
},
"sim_label": "valid-example"
}
SMS
This event occurs when a device sends an SMS to any number, displaying the SMS content and information about the SMS destination. This is only triggered when the SMS originates from the device.
Benefits:
Tracks application-level messaging behavior.
Helps detect unauthorized use or unexpected communication patterns.
Allows you to capture SMS content outside of the Onomondo platform.
If you are interested in capturing SMS with webhooks, see this guide:
Example:
{
"type": "sms",
"time": "2025-04-09T10:45:37.409Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"sim_label": "valid-example",
"to": 453388326,
"text": "Hello World!",
"text_base64": "SGVsbG8gV29ybGQh"
}
SMS Usage
In contrast to the above, SMS usage events occur whenever someone:
Sends an SMS to a device (
"direction": "outgoing"). Either by using the API POST SMS to a device or from the SIM tab on the platform.An SMS is sent from a device (
"direction": "incoming"). The information in the text from the device needs to be captured from the webhook event or by being in the specific SIMs detail page at the time (and viewed on the SMS Tab).
Benefits:
Provides detailed insight into bidirectional messaging.
Useful for billing, diagnostics, and monitoring device interactions.
Allows usage-based alerting or automation, e.g., trigger actions after X SMS messages.
Example (SMS sent from the device):
{
"type": "usage-sms",
"sim_label": "valid-example",
"id": "85eec601-45cb-471b-87ed-876bfa7b7833",
"session_id": "310ca71b-7894-326b-bdcd-ad80e067a32b",
"time": "2020-11-30T10:39:04.447Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"direction": "outgoing",
"status": "success",
"retries_left":9,
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
}
}
Example (SMS sent to the device):
{
"type": "usage-sms",
"sim_label": "valid-example",
"id": "79224583-e41b-431c-a4de-48f9c16e0297",
"session_id": "b57d0945-8cca-3fb8-8d49-038a11cb2188",
"time": "2020-11-30T10:39:20.329Z",
"sim_id": "000000001",
"iccid": "8945738730000000012",
"direction": "incoming",
"status": "success",
"retries_left":null,
"network": {
"name": "TDC A/S",
"country": "Denmark",
"country_code": "DK",
"mcc": "238",
"mnc": "01"
}
}
Managing webhooks
You can also use a tag to associate the Webhook with only a set portion of your SIMs (defined by the tag).
Tags are one of the key management features in the Onomondo app. You can read more about them here:
It is generally recommended to create different webhooks for different subsets of SIMs, depending on your needs. Then, you can choose the most relevant events for the right SIMs.
In addition, you can consider duplicating the same webhook and sending the same data towards different endpoints. There are no limits to how many webhooks you set up.
The only restriction is that each webhook created in the Onomondo app can be paired with one single endpoint.
Want to try setting up a test webhook? Check out this guide: