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
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
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
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
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
JSON webhook body when usage exceeds 1GB
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