Webhooks

A webhook is a way for an application or service to provide real-time notifications to other applications or services. Webhooks are typically used to trigger an event or action in one application or service based on a specific activity or event in another application or service.

Simbase uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like IMEI changes, usage monitoring or receiving SMS messages.

Ready to go live? Register your webhook endpoint on the Dashboard so Simbase knows where to deliver events.

How Simbase uses webhooks

A webhook enables Simbase to push real-time notifications to your app. Simbase uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems. To learn more, see Stripe webhook events overview.

Webhook events

Simbase supports the following event types:

Received SMS messages

Simbase SIM cards can communicate directly to our servers in a closed SMS circuit. When your device sends an SMS to our server (+55555) it will become visible on our platform. Optionally, you can forward the SMS message over HTTP to your SMS webhook. Read more about SMS here.

JSON webhook body

{
  "event": "sms",
  "iccid": "8912300000001234567",
  "timestamp": "2022-12-23 12:31:09",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

IMEI change

An IMEI (International Mobile Equipment Identity) is a unique identification number that is assigned to every mobile device. It is used to identify the device on a mobile network and is typically used to track the device's location, authenticate it on the network, and enable it to access various services and features.

If your SIM is used in a different device, the network will detect an IMEI change. We can inform your webhook when this happens.

JSON webhook body

{
  "event": "imei",
  "timestamp": "2022-12-23 12:34:07",
  "iccid": "8912300000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

SIM state changes

The SIM state of a SIM card refers to its current status or condition, and it can change based on various factors such as:

Manual activation or deactivation via platform or API
Automatic activation
Depleted balance
Incidents (theft, fraud, etc)
IMEI changes

When any of these events occur, Simbase can send a notification to your webhook. Read more about SIM states here.

JSON SIM state change

{
  "event": "sim_state",
  "timestamp": "2022-12-23 12:42:57",
  "iccid": "8912300000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Throttling

In the Simbase dashboard, you can set Traffic Policies, which automatically throttles the data connection of your SIM card after the monthly data usage has exceeded a certain threshold. Read more on throttling here.

JSON webhook body

{
  "event": "throttle",
  "timestamp": "2022-12-23 13:10:15",
  "iccid": "8912300000001234567",
  "speedKBps": 100
}

Usage exceeds threshold

Even without enabling Traffic Policies, you can receive a notification if your SIM card's monthly data usage has exceeded a certain threshold. There are two pre-defined thresholds:

Monthly data usage exceeds 100MB
Monthly data usage exceeds 1GB

JSON webhook body when usage exceeds 100MB

{
  "event": "limit.100mb",
  "timestamp": "2022-12-23 13:13:24",
  "iccid": "8912300000001234567",
  "usageBytes": 104857600,
  "usageMegaBytes": 100,
  "deviceName": "Demo device"
}

JSON webhook body when usage exceeds 1GB

{
  "event": "limit.1gb",
  "timestamp": "2022-12-23 13:13:56",
  "iccid": "8912300000001234567",
  "usageBytes": 1048576000,
  "usageMegaBytes": 1000,
  "deviceName": "Demo device"
}

Steps to receive webhooks

You can start receiving event notifications in your app using the steps in this section:

Identify the events you want to monitor and the event payloads to parse.
Create a webhook endpoint as an HTTP endpoint (URL) on your local server.
Handle requests from Simbase by parsing each event object and returning 2xx response status codes.
Test that your webhook endpoint is working properly using Postman.
Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
Register your publicly accessible HTTPS URL in the Simbase dashboard.
The platform will send a test notification to your webhook. If a 20X status code is received, the webhook will be saved.

Specifications

Method

All calls on your webhooks from the Simbase servers will be POST calls.

Security

Each call on your webhook will have the header x-simbase-requesttoken in it. For all test calls, the value is: test-test-test-test-test
You can verify the authenticity of the call made on your webhook via our API. Read more here.
Please do not use IP filtering as a security measure. Our servers are globally distributed and use several different public IP addresses.

Retry scheme

If your endpoint does not respond with a 2XX status code, the call will be scheduled for a retry. After 15 minutes, our servers will make another attempt. If that call also fails, a new retry is scheduled.

When our system still did not receive a 2XX status code after 3 attempts, the message is discarded and we send you an email to notify you.

Last updated 2 months ago