Events: real-time notifications from your SIMs

Events tell your systems the moment something happens on your Simbase SIMs. A device sends an SMS, a SIM is moved into a new device, a SIM is disabled, a usage limit is crossed: Simbase sends the details to a URL you choose, within seconds, so you never have to poll the API to find out.

Events replace the legacy webhooks. They cover the same situations and add a few things customers have been asking for: more event types, one destination for many event types, signed requests you can verify, a delivery log and longer retries.

Ready to go live? Add a destination on the Integrations page of the dashboard.

Already using webhooks?Nothing breaks. Legacy webhooks keep working for the foreseeable future, but they won't get new features. Make sure to use Events for anything new.

How Events work

Two ideas cover everything:

  • An event is a record of one thing that happened, like "SIM 8900…567 sent an SMS". Every event has a type, a unique ID, a timestamp and the details that belong to its type.

  • A destination is where events are sent. Today that's a webhook: an HTTPS URL that receives each event as a JSON POST request.

When an event happens, Simbase sends it to every destination whose filter matches its type. Your endpoint replies with a 2xx status code.

The URL can be anything that accepts a POST request over HTTPS:

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

  • A team chat tool like Slack or Microsoft Teams (usually with Zapier or Make.com in between to reshape the message)

  • A route on your own backend, in any language

  • A serverless function on AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions and similar

What's new compared to webhooks

  • More event types. SMS sent to a SIM and every new usage record (CDR) are now available, on top of the four legacy events.

  • One destination, many events. A legacy webhook carried one event type. A destination's filter can include as many event types as you like, or all of them.

  • Signed requests. Every request carries a signature, so your endpoint can confirm it really came from Simbase and wasn't changed on the way.

  • Duplicate-safe. Each event has a unique event_id that stays the same on every delivery attempt.

  • Longer retries. Failed deliveries are retried with backoff for up to 4 hours, instead of three attempts.

  • Delivery log. You can see the last 15 days of delivery attempts for each destination, including failures.

  • Polling as a fallback. Events are kept for 30 days and can also be read through the API, without a destination.

Event types

Event type names are made of parts separated by dots, from general to specific, like simcard.sms.mo. A filter can match a full event type or just the start of the name, so one filter can cover several related event types at once.

SMS events use the standard mobile terms. MO (mobile originated) is an SMS sent by the SIM, from the device to Simbase. MT (mobile terminated) is an SMS sent to the SIM, from the dashboard or the API to the device.

Event type
  • simcard.sms.mo
  • simcard.sms.mt
  • simcard.security.imei_changed
  • simcard.state.enabled
  • simcard.state.disabled
  • simcard.usage.threshold_exceeded
  • simcard.usage.cdr

Filtering events

When you create a destination, its filter decides what it receives:

  • A single event type, like simcard.state.disabled, for "tell me when a SIM goes offline".

  • A prefix, like simcard.sms, for every event type that starts with it. Here, that's both MO and MT SMS.

  • Everything: leave the filter empty to receive every event type.

Go easy on CDRssimcard.usage.cdr is by far the busiest event type: an active SIM can produce many records a day. A filter of simcard or simcard.usage includes it. Only include CDRs if you actually store or process usage records, and make sure your endpoint can handle the volume.

What people build with Events

  • SMS from devices (MO): forward device messages to Slack or Teams, log them to a Google Sheet through Zapier, parse sensor readings into your database, or relay them to a phone number through Twilio. See SMS.

  • SMS to devices (MT): confirm that a command or configuration SMS left for a device, and keep a log of what was sent.

  • IMEI changed: alert operations or open a ticket when a SIM turns up in an unexpected device, or disable it through the API. The event includes the SIM's theft protection status, so you know whether the change was blocked.

  • SIM enabled or disabled: keep your CRM or asset database in sync, alert support before the customer calls, or start billing when a SIM goes live. See SIM state.

  • Usage threshold exceeded: catch a runaway device early, open a PagerDuty incident, or notify the device owner. See Usage limits.

  • CDRs: stream usage into your own billing or analytics instead of exporting it.

What an event looks like

Every request has the same outer shape, the envelope, with the event's details inside the event field. Here's an SMS sent by a device:

{
"event_type": "simcard.sms.mo",
"event_id": "01KPX0BH46PVJ89YE6446Q086M",
"timestamp": "2026-11-13T09:30:12.418000Z",
"correlation_id": "123e4567-e89b-12d3-a456-426614174001",
"customer_id": "C123123123123",
"event": {
"iccid": "8900000000001234567",
"message": "temp=21.4;door=closed",
"timestamp": "2026-11-13T09:30:11Z"
}
}

What each envelope field is for:

  • event_type tells you which event this is, and so which fields to expect in event.

  • event_id is unique to this event and the same on every retry. Use it to ignore duplicates.

  • timestamp is when Simbase recorded the event, in UTC (RFC 3339).

  • correlation_id links the event to whatever caused it. Include it when you contact support about an event.

  • customer_id is your Simbase account.

Only the event part changes between types. Two more examples:

IMEI changed

{
"event": {
"iccid": "8900000000001234567",
"imei_old": "356938035643021",
"imei_new": "356938035643039",
"imei_lock": "off"
}
}

Usage threshold exceeded (usage in bytes, threshold is null if not set)

{
"event": {
"iccid": "8900000000001234567",
"usage_data": 105906176,
"usage_sms": 3,
"threshold_data": 104857600,
"threshold_sms": null
}
}

The other types follow the same pattern. SIM state events carry the iccid. CDRs carry the start and end time, type, volume and network (MCC and MNC). The full field list for every type is in the API reference.

Set up a destination

  1. Decide what you need. Which event types, and which fields in them you'll use. Start small; you can change the filter later.

  2. Get an HTTPS URL that accepts POST requests: a route on your backend, a serverless function, or a Zapier or Make.com webhook URL. It must be reachable from the public internet.

  3. Add the destination. In the dashboard, open Integrations and add a new destination. Enter the URL, give it a name you'll recognize, and set the Filter to the event types you want.

  4. Save the signing secret. The dashboard shows a secret starting with whsec_. It's shown only once, so store it somewhere safe, like your password manager or your app's secrets store.

  5. Reply fast. Your endpoint should return a 2xx status as soon as the request arrives, and do the real work afterwards.

  6. Verify the signature before acting on an event. See Security.

  7. Watch the delivery log for the first few events, to confirm they arrive and your endpoint answers with 2xx.

You can also create and manage destinations through the API, using an API key with the integrations scopes.

Specifications

Method and headers

Every delivery is an HTTPS POST with a JSON body, sent only to public IP addresses. Each request includes these headers:

  • webhook-id, webhook-timestamp and webhook-signature, used to verify the request

  • X-Simbase-Integration-Id, the destination the request was sent to

Security

Requests are signed following the open Standard Webhooks specification. Simbase signs each request with your destination's whsec_ secret and puts the result in the webhook-signature header. Checking it proves the request came from Simbase and wasn't tampered with.

The easiest way is one of the free Standard Webhooks libraries, available for most languages: pass in the raw request body, the headers and your secret, and the library does the rest, including rejecting old requests. The API reference also has a short example for checking it without a library.

Two things to keep in mind:

  • Check the raw body. Verify the signature against the body exactly as it arrived, before your framework parses or reformats the JSON.

  • Don't rely on IP allowlists. Simbase's servers are globally distributed and the addresses they send from change over time. The signature is the reliable check.

If you're sending events to a no-code tool that can't check signatures, treat the URL itself as a secret and don't share it.

If your server uses a self-signed TLS certificate, you can turn off certificate verification for that destination.

Delivery and retries

  • At least once. An event can arrive more than once. Use event_id to ignore repeats.

  • Not always in order. Events can arrive in a different order than they happened. Sort by timestamp when order matters, for example for state changes.

  • What counts as success: any 2xx status code.

  • Retried with backoff for up to 4 hours: timeouts, 408, 429 and 5xx responses. A Retry-After header is respected.

  • Not retried: any other status code, redirects included.

  • Suspended immediately: a 410 Gone response suspends the destination.

  • Suspended after 48 hours: a destination that keeps failing for 48 hours straight is suspended. Re-enable it from the dashboard or the API to start receiving new events again.

RetentionEvents are kept for 30 days. Delivery attempts are visible for 15 days.

Moving from legacy webhooks

Legacy webhooks keep working, so you can move at your own pace. Each legacy event has a direct equivalent:

Legacy webhook
  • Received SMS (sms)

  • IMEI change (imei)

  • SIM state change (sim_state)

  • Usage limits reached (usage_limits)

What changes in the payload:

  • The details move inside an event field, wrapped in the envelope described above.

  • Timestamps are in RFC 3339 format, in UTC, like 2026-11-13T09:30:12Z.

  • A state change is now two event types, one for enabled and one for disabled, instead of old_state and new_state fields.

  • Data usage is in bytes rather than MB.

  • The device name isn't included. Look it up by ICCID if you need it.

A safe way to switch:

  1. Add a destination for the same event types, pointing at a new route on your endpoint.

  2. Update your code to read the new payload and verify the signature.

  3. Run both side by side for a few days and compare. Expect each change to arrive twice during this time, once per system.

  4. Delete the legacy webhook under Integrations → Webhooks.

Common questions

No. Legacy webhooks keep working for the foreseeable future, but won't get new features. New integrations should use Events.

Delivery is at least once, so a retry can arrive after your endpoint already processed the first attempt. Store the `event_id` of events you've handled and skip any you've seen.

It either returned `410 Gone` or failed for 48 hours straight. Fix the endpoint, check the delivery log for the error, then re-enable the destination on the Integrations page. Events from while it was suspended aren't re-sent, but you can still read them through the API for 30 days.

Yes, by polling them through the API. Polling counts against your API quota, so a destination is the better choice for anything live.

Yes. Create a destination for each URL, each with its own event types.

No. TLS is enforced to ensure data privacy and secure communication. However, you can still use a self-signed certificate and disable TLS certificate verification on the destination side.

  • Webhooks (legacy): the previous way to receive events, still supported

  • API keys: create a key with the scopes needed to manage destinations

  • SMS: the messages behind the SMS events, and how they differ per profile

  • Theft protection: lock a SIM to one IMEI, reported in IMEI change events

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

  • Usage limits: set the thresholds behind threshold events

  • API: manage destinations and poll events programmatically