Webhooks Reference

Lets you subscribe to certain events regarding SIMs and process the event notifications through an integration or app.

Webhooks are a way of sending you events specific to your SIMs when something happens. We will deliver the events as HTTP POST calls.

This enables you to act on things happening with you IoT fleet in near to real-time, such as knowing when/if a SIM changes its physical location, SIMs registering to networks, ingest all of your fleet's usage, or get notified when usage threshold (alerts) are reached.

The current Webhooks that Onomondo supports can be seen in the following table.

Name (in the web app)
Type indicated in POST call
Description

Data Usage

usage

Includes information about the data usage of per SIM, i.e. how many bytes the SIM has sent over a specific network.

SMS Usage

usage-sms

Usage data around in- and outgoing SMSs.

Usage Alerts

usage-alert

Occurs when a SIM has reached a certain amount of data usage, e.g. the alert threshold (soft) or the usage limit (hard).

Cost Alert

cost-alert

Occurs when a SIM has reached a certain amount of cost, which is set by cost alert threshold.

Network Registration

network-registration

Information around when a device attaches to a network.

Network Deregistration

network-deregistration

Information around when a device detach from a network.

Network Authentication

network-authentication

Contains information around when a device has attempted to authenticate for a specific network, occurs both when a device successfully authenticates as well as when it is denied.

SMS

sms

Contains the text/payload of outgoing SMSs from a device perspective.

Location Update

location

Information around the physical location of the cell that the device has attached to, wherein the cell is a subarea of the total area that a cell tower/base station covers.

Back off timers and circuit breakers

Your endpoint will need to respond with a status code of 200 in order for the request to be considered successfully delivered. If your endpoint does not respond with a status code 200 or doesn't reply within one second then the delivery will be considered unsuccessful. We will try to deliver an event 10 times. If the event is still not delivered successfully on the 11th attempt then the event is discarded.

Any issues with delivering to your will be added to the Error Logs.

The back off times are:

1. attempt: Instant
2. attempt: 10 seconds
3. attempt: 30 seconds
4. attempt: 1 minute 10 seconds
5. attempt: 2 minutes 30 seconds
6. attempt: 5 minutes 10 seconds
7. attempt: 10 minutes 30 seconds
8. attempt: 21 minutes 10 seconds
9. attempt: 42 minutes 30 seconds
10. attempt: 1 hour 15 minutes 10 seconds
11. attempt: 2 hours 50 minutes 30 seconds

Moreover, then Onomondo uses a circuit-breaker pattern with an error rate at 50% over a 10 second sliding window as well as a probe configured at every 10 seconds for any endpoint in the half-open state. The back off times still apply. This means that if you have an endpoint that is failing over a longer period of time then it is not guaranteed that 11 delivery attempts are made.

Webhook Signature Verification

All outgoing requests from Onomondo will include a cryptographic signature, HMAC, that allows you to verify the authenticity and integrity of the payload.

The signature is provided in the X-Onomondo-Signature-256 header and follows this format:

sha256=20d1121489c9eaa2454bd203cad63c90b8309042c2cab75b31812b5feb2c29f6

To verify the signature on your end compute the HMAC-SHA256 of the request body using your secret, which can be found in Edit page for the specific Webhook in the web app. Then compare it with the hash provided in the header (after the sha256= prefix). If they match, you can be confident that the request originated from Onomondo and hasn't been tampered with.

Usage related Webhooks

Data usage

Data usage, which is default webhook type ("type": "usage"), occurs per SIM approximately every 15 minutes and after a network deregistration. This provides the same information as using the GET /usage API call.

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": "000002273",
    "iccid": "89457387300000022734",
    "ipv4": "100.66.133.212",
    "imei": "3554014423671441"
    "bytes": 9484,
    "network": {
        "name": "TDC A/S",
        "country": "Denmark",
        "country_code": "DK",
        "mcc": "238",
        "mnc": "01"
    },
    "sim_label": "iphone",
}

SMS usage

SMS usage events occur when ever 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).

This is the same as the API GET /usage/sms request or on the platform when looking at the SMS tab at a specific SIM.

An SMS is received by the device when "status": "success" with regards to GET /usage/sms. If the SMS was not successfully delivered an error type will be displayed instead, such as "status": "absentSubscriber". This could for instance occur in the scenario where a device is or goes goes offline before the SMS is delivered.

Example:

{
  "type": "usage-sms",
  "sim_label": "iphone",
  "id": "85eec601-45cb-471b-87ed-876bfa7b7833",
  "session_id": "310ca71b-7894-326b-bdcd-ad80e067a32b",
  "time": "2020-11-30T10:39:04.447Z",
  "sim_id": "000002273",
  "iccid": "89457387300000022734",
  "direction": "outgoing",
  "status": "success",
  "retries_left": 9,
  "network": {
    "name": "TDC A/S",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "01"
  }
}

Usage Alerts

Usage alerts, which is default Webhook type ("type": "usage-alert"), is sent based on the data limits set on a specific SIM. There are two types of events.

Alert threshold

When the usage of a SIM in a period reaches the SIM's specified usage threshold an event is sent. Included in the event object is the reason ("reason": "alert-threshold"). When a device reaches the threshold it will not be cut off from using more data but instead serves as a way for users to be warned about data consumption.

Example:

{
  "type": "usage-alert",
  "reason": "alert-threshold",
  "time": "2021-12-01T10:08:36.530Z",
  "sim_id": "000000001",
  "iccid": "89457387300000000105",
  "ipv4": "100.96.0.1",
  "data_limit": {
    "used": 1101976,
    "total": 2000000,
    "type": "monthly",
    "period": "202112",
    "alert_threshold": 1000000,
    "resets_at": "2022-01-01T00:00:00.000Z"
  },
  "sim_label": "foobar"
}

Data limit reached

When the usage of a SIM in a period reaches the SIM's specified data limit an event is sent. Until the limit period is reset the device will be able to connect to a network but not send any more data.

Included in the event object is the reason ("reason": "blocked"). Note that the used field might be a little above or below the actual data usage which is due to differing sampling rates.

Example:

{
  "type": "usage-alert",
  "reason": "blocked",
  "time": "2021-12-01T10:09:41.571Z",
  "sim_id": "000000001",
  "iccid": "89457387300000000105",
  "ipv4": "100.96.0.1",
  "data_limit": {
    "used": 1934264,
    "total": 2000000,
    "type": "monthly",
    "period": "202112",
    "alert_threshold": 1000000,
    "resets_at": "2022-01-01T00:00:00.000Z"
  },
  "sim_label": "foobar"
}

Cost Alert

Cost alerts, which is default type (“type”:”cost-alert”), is sent based on the cost alert threshold set on an individual SIM.

When the cost related to a SIM in a specific period reaches the specified cost alert threshold an event is sent, it will not be cut off from using more data, sending SMSs, attaching to networks, etc., but instead it serves as a warning.

Example:

{
  "sim_id": "000002273",
  "period": "monthly",
  "threshold": 10,
  "total_cost": 10,
  "type": "cost-alert"
}

Network Log related Webhooks

All registration, deregistration, and authentication logs for all SIMs as per the API call to retreive Network Logs of a SIM.

Network Registration

A Network Registration occurs when a SIM attaches to or deattaches from our network through the local base station. Once the registration has occurred the device will be able to send/receive SMSs (with a GSM connection) and send/receive data (through a 2G/3G/4G data connection).

Example a GSM Network Registration, i.e. a registration wherein the device can only receive and send SMSs:

{
  "id": "c73606fe-ebae-4f20-9d79-bd057f94f1dd",
  "time": "2020-04-23T11:38:39.688Z",
  "type": "network-registration",
  "sim_id": "000002273",
  "iccid": "89457387300000022734",
  "network_type": "GSM",
  "imei": null,
  "network": {
    "name": "Hi3G",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "06"
  },
  "sim_label": "iphone"
}

Example of a 3G Network Registration:

{
    "type": "network-registration"
    "id": "913ed25e-310f-3194-9102-fef88fa9478d",
    "session_id": "0afcd0cd-3119-3b6b-a7c2-dc6a9fe1f414",
    "time": "2024-04-04T08:56:48.462Z",
    "sim_id": "000002273",
    "iccid": "89457387300000022734",
    "imei": "3554014423671441",
    "network_type": "3G",
    "network": {
        "name": "Hi3G",
        "country": "Denmark",
        "country_code": "DK",
        "mcc": "238",
        "mnc": "06"
    },
    "ipv4": "100.66.133.212",
    "sim_label": "iphone",
}

Network Deregistration

See the description of Network Registration.

Example:

{
    "type": "network-deregistration"
    "id": "055d86a5-798b-3129-bd52-7eb931ca1d0a",
    "session_id": "965e15f7-7e3d-3af0-8c70-d165e4fed793",
    "time": "2024-04-04T08:56:50.963Z",
    "sim_id": "000002273",
    "iccid": "89457387300000022734",
    "imei": "3554014423671441",
    "network_type": "3G",
    "network": {
        "name": "Telia",
        "country": "Denmark",
        "country_code": "DK",
        "mcc": "238",
        "mnc": "20"
    },
    "ipv4": "100.66.133.212",
    "session_usage": {
        "upload": 2016,
        "download": 3298
    },
    "sim_label": "iphone",
}

Network Authentication

Before the device can attach to a base station, it needs to confirm with us, if it is allowed. When the device asks permission to attach to the base station, a network-authentication event occurs.

When status and reason properties are null, then the SIM was authenticated and it is allowed to attach to our network. If an authentication is blocked, the information will be provided in these properties.

Example of a successful authentication:

{
  "type": "network-authentication",
  "id": "b0f57875-d79d-4493-8b02-c82e85f862e6",
  "time": "2020-11-30T10:21:53.623Z",
  "sim_id": "000002273",
  "sim_label": "iphone",
  "iccid": "89457387300000022734",
  "imei": null,
  "status": null,
  "reason": null,
  "network_type": "2G/3G",
  "network": {
    "name": "TDC A/S",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "01"
  }
}

Example of an authentication attempt that was denied:

{
  "type": "network-authentication",
  "id": "bd98099b-323d-46d8-b8a7-2376475ec9f9",
  "time": "2020-11-30T12:24:56.878Z",
  "sim_id": "000002273",
  "sim_label": "iphone",
  "iccid": "89457387300000022734",
  "imei": null,
  "status": "operatorDeterminedBarring",
  "reason": "network_whitelist",
  "network_type": "GSM",
  "network": {
    "name": "Hi3G",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "06"
  }
}

SMS

All SMSs from a device come through the Webhook as an event. The typical body of the POST request includes:

  • "time" sent.

  • ID of the SIM (both "sim_id" and "iccid").

  • "sim_label".

  • A destination the device has sent it "to".

  • And the actual SMS ("text") as well as the raw SMS without any decoding but encoded using Base64 ("text_base64").

Example:

{
  "type": "sms",
  "time": "2024-04-09T10:45:37.409Z",
  "sim_id": "000002273",
  "iccid": "89457387300000022734",
  "sim_label": "iphone",
  "to": 453388326,
  "text": "Hello World!",
  "text_base64": "SGVsbG8gV29ybGQh"
}

Location Update

Location events occur at the beginning and end of sessions, as well as if the location changes during a session. This is an approximate location, when possible it will also include the "accuracy" in meters radius.

Some of the same information as using the GET "Retrieve specific SIM information" API request when a SIM is online.

Not all sessions can we determine location. In these situations accuracy, lat, and lng values will be null.

Example:

{
  "type": "location",
  "imei": "3518650966887220",
  "iccid": "89457387300002010000",
  "sim_id": "000201000",
  "location": {
    "cell_id": 31508,
    "location_area_code": 183,
    "accuracy": 2873, // in meters radius
    "lat": "56.702866",
    "lng": "14.6013649"
  },
  "network": {
    "name": "TDC A/S",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "01"
  },
  "network_type": "3G",
  "sim_label": "Motorola3_ValidSIM",
  "time": "2020-07-02T12:46:42.105Z",
  "ipv4": "100.96.0.117",
  "session_id": "965e15f7-7e3d-3af0-8c70-d165e4fed793"
}
PreviousWebhooksNextIP Ranges

Last updated