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 and usage limits.

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

• Usage limits reached

Received SMS messages

Black, Red and Green SIMs live inside what we call a closed SMS circuit. In plain terms: the 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.

Blue, Yellow and Cyan SIMs ship with an MSISDN, so external numbers can text them. Messages those devices send still stay inside Simbase and are never delivered to an outside phone, so the webhook behaves the same way on every profile. See SMS for the per-profile detail.

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.

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. See SMS.

JSON webhook body

{
  "event": "sms",
  "iccid": "8900000000001234567",
  "timestamp": "2026-08-06 12:00:00",
  "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": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "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 or disabled. 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

• Unauthorized IMEI changes

When the state changes, Simbase posts the new state to your webhook so the rest of your stack can react. See SIM state.

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": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Usage limits reached

You can set a monthly data or SMS cap on any SIM. When usage passes that cap, Simbase disables the SIM automatically, and this webhook tells the rest of your stack the moment it happens.

Caps are checked when usage records arrive from the operator rather than in real time, so a SIM can finish slightly over its cap before it is disabled. See Usage limits for why that overshoot happens and how to budget for it.

This is a clean way to catch a misbehaving device early. A SIM that normally uses 10 MB a month and suddenly hits its cap 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, so the team knows a SIM has gone offline before the customer calls

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

• Check the device, then re-enable the SIM or raise its limit through the Simbase API

• Trigger a Zapier or Make.com flow that notifies the device owner

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

JSON webhook body

{
  "event": "usage_limits",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "usage_mb": 102,
  "threshold_mb": 100,
  "usage_sms": 0,
  "threshold_sms": null
}

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 → Webhooks.

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

• 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.

Common questions

Related

• SMS, the messages the received-SMS webhook forwards, and how they differ per profile

• Theft protection, lock a SIM to one IMEI so a change is blocked, not just reported

• SIM state, what Enabled and Disabled mean and what changes them

• Usage limits, set the cap that triggers the usage webhook

• API, list, create, and delete webhooks programmatically