A webhook is a message your app receives the moment something happens, instead of having to ask "anything new yet?" on a loop. When an event happens inside your Simbase account, Simbase pushes that event to a URL you control, in real time.

This is how you wire Simbase into the rest of your stack. An SMS arrives on a SIM and your Slack channel pings. A device swaps IMEI and your ticketing system opens an incident. Monthly data crosses a threshold and your usage dashboard updates. All of it without writing code that polls our API.

Webhooks cover the events that happen on Simbase's side of the world: incoming SMS, IMEI changes, SIM state changes, throttling and usage thresholds.

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

How Simbase uses webhooks

When something happens on your account, Simbase makes an HTTPS POST to the URL you specify, with a JSON body describing the event. Your app reads the body, does whatever you want with it, and replies with a 2xx status code to confirm the message was received.

You do not have to build something fancy on the receiving side. The "URL you specify" can be any of these:

• A no-code automation platform like Zapier or Make.com

• A team chat tool like Slack or Microsoft Teams, using their built-in incoming webhook URLs (directly or with Zapier or Make.com in between)

• A function on your own backend, in any language

• A third-party SMS provider like Twilio or MessageBird, if you want to relay SMS messages out to public phone numbers

• A serverless function on AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions, etc.

If you can give us an HTTPS URL, we can deliver events to it.

Webhook events

Simbase supports the following event types:

• Received SMS messages

• IMEI changes

• SIM state change

• Throttling

• Usage exceeds threshold

Received SMS messages

Simbase SIM cards live inside what we call a closed SMS circuit. In plain terms: your SIM can send SMS to our server at the short number +55555 and receive SMS from our server, but it cannot exchange SMS with any other phone number in the world. This is on purpose. It is a security measure that keeps your fleet unreachable from the public SMS network, so nobody can text your devices, no premium-rate scam can drain your balance, and SMS cannot be used as an attack surface against your hardware.

You can still send and receive SMS from your devices, of course. The messages just flow through Simbase instead of through the public mobile network. And that is exactly where this webhook becomes powerful.

When your device sends an SMS to +55555, two things happen:

1. The message becomes visible on the Simbase dashboard.

2. If you have an SMS webhook registered, Simbase forwards the full message over HTTPS to your endpoint.

That second step is the part most customers underestimate. The payload contains the message body, the ICCID of the SIM, the device name and a timestamp. Once that lands on your endpoint, you can do anything you want with it.

A few real examples of what people build with this webhook:

• Forward the SMS body to a Slack or Microsoft Teams channel so the team sees device messages live. Useful for asset trackers, vending machines, remote sensors or any device that reports by SMS.

• Pipe the payload into Zapier or Make.com and trigger anything those platforms support: log to Google Sheets, send an email, update a CRM, create a Zendesk or Intercom ticket, post to Notion, etc. No code required.

• Relay the SMS to an external phone number through Twilio, MessageBird or any other SMS provider. Your device sends an SMS through Simbase, your webhook receives it, your code forwards the body to Twilio, and Twilio delivers it to a regular mobile phone. This is how customers build a one-way bridge from a locked-down IoT fleet to a normal phone number, without giving up the security of the closed circuit.

• Parse the SMS body for sensor readings or commands and store them in your own database or a time-series store like InfluxDB or TimescaleDB.

• Trigger an action back on the SIM. Your endpoint receives the SMS, decides "this device is misbehaving", and calls the Simbase API to disable the SIM, throttle it or move it to a different policy.

For readers who do not write code, the short version is this: the SMS webhook is what turns "an SMS arrived on a SIM" into "Slack got pinged", "the spreadsheet updated", "the team got an email" or "a ticket was opened". You do not have to learn how SMS routing works. You just have to point Simbase at the right URL. 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

Every device has an IMEI (International Mobile Equipment Identity), a unique 15-digit identifier baked into the hardware. When your SIM is moved into a different device, the mobile network detects the new IMEI and reports it. Simbase can let your endpoint know the moment that happens.

Why this matters depends on your business. For asset tracking, logistics or fleet management, an unexpected IMEI change is one of the strongest signals that a SIM has been pulled out of its intended device, either through theft, tampering or maintenance going sideways. For OEMs shipping pre-provisioned devices, IMEI change events are how you confirm that each SIM ended up in the device it was supposed to.

What people typically do with this webhook:

• Post the event to Slack or email so your operations team can look into it.

• Open a ticket automatically in your support tool when the new IMEI does not match an expected device.

• Disable the SIM through the Simbase API if your security policy treats unexpected IMEI changes as a fraud signal.

• Log the change in your asset database so you always know which SIM is in which device, without manual reconciliation.

• Push the event into a SIEM or audit log for compliance and forensics.

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

A SIM card has a state that describes whether it is currently enabled, disabled, suspended and so on. The state can change for several reasons:

• Manual activation or deactivation through the dashboard or the API

• Automatic activation when the SIM is first used

• Depleted balance

• Incidents like theft or suspected fraud

• IMEI changes that trigger a policy

When the state changes, Simbase posts the new state to your webhook so the rest of your stack can react. Read more about SIM states here.

What customers tend to do with this event:

• Keep an internal CRM, ERP or asset database in sync with the real state of every SIM, without polling the Simbase API.

• Get a Slack or email alert the moment a SIM is disabled, so support hears about it before the customer calls.

• Kick off billing automation when a SIM is activated for the first time, by sending the event into Stripe, Chargebee or a custom billing service through Zapier or your own backend.

• Catch surprises early. If a SIM was disabled and nobody on your team expected it, treat that as an incident automatically.

JSON webhook body

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

Throttling

You can set Traffic Policies in the Simbase dashboard to automatically cap a SIM's data speed once its monthly usage crosses a threshold you choose. When a SIM gets throttled, Simbase can fire a webhook so you do not find out about it from a frustrated customer.

A few useful follow-ups once the event arrives at your endpoint:

• Email or text the device owner with a clear message: "your device is throttled to 100 KB/s until the end of the month".

• Push a card into your support tool so the team is ready when a "slow connection" complaint comes in.

• Update a customer-facing dashboard so the customer can see exactly when the throttle started.

• Trigger an upsell or plan upgrade flow if a customer keeps hitting the cap.

• Send the event to Slack so engineering sees throttling patterns across the fleet in real time.

JSON webhook body

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

Usage exceeds threshold

Even without setting a Traffic Policy, you can have a webhook fire when a SIM's monthly data usage crosses a fixed threshold.

This is a clean way to catch a misbehaving device early. A SIM that normally uses 10 MB a month and suddenly crosses 100 MB is usually trying to tell you something: a firmware bug, a Wi-Fi fallback that went wrong, a device left in debug mode, a runaway OTA update or, in the worst case, a stolen SIM being used for tethering.

Things customers tend to do with this event:

• Send an alert to Slack or email when a SIM crosses the set limit,

• Open an incident in PagerDuty or Opsgenie for high-priority deployments.

• Throttle or disable the SIM automatically through the Simbase API.

• Trigger a Zapier or Make.com flow that pings the device owner with a notification before the bill grows.

• Log the event into a usage anomaly dashboard so you can spot fleet-wide trends over time.

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"
}

Steps to receive webhooks

You can start receiving event notifications in your app in a few steps:

1. Decide which events you want to listen to and which fields in the payload you actually care about.

2. Create an HTTP(S) endpoint to receive the events. This can be a route on your backend, a serverless function, a Zapier webhook URL, a Make.com webhook URL, a Slack incoming webhook (with a small transformation in front), or any other URL that accepts POST requests.

3. Parse the JSON body on your side and return a 2xx status code. Only the status code matters to Simbase, not the response body.

4. Test the endpoint with a tool like Postman or curl. If you want to receive real Simbase events while developing on your laptop, a tunneling tool like ngrok or Cloudflare Tunnel works well.

5. Deploy your endpoint behind a publicly reachable HTTPS URL.

6. Register that URL in the Simbase dashboard under Integrations.

7. Simbase sends a test event to your URL. If your endpoint replies with a 2xx code, the webhook is saved and starts receiving live events.

Specifications

Method

All calls from Simbase to your webhook are HTTP POST requests with a JSON body.

Security

• Every call carries a header named x-simbase-requesttoken. For test calls the value is test-test-test-test-test. Use this header on your side to confirm that the request actually came from Simbase before acting on it.

• Do not use IP filtering as a security measure. Our servers are globally distributed and the public IPs they send from change over time, so an IP allowlist will break at the worst possible moment.