Webhooks instellen in Simbase

Een webhook is een bericht dat je app ontvangt zodra er iets gebeurt, zodat je niet steeds in een lus hoeft te vragen: "is er al iets nieuws?" Gebeurt er iets in je Simbase-account, dan stuurt Simbase dat event direct naar een URL die jij beheert.

Zo koppel je Simbase aan de rest van je stack. Er komt een sms binnen op een SIM en je Slack-kanaal krijgt een melding. Een apparaat wisselt van IMEI en je ticketsysteem opent een incident. Het maandelijkse dataverbruik passeert een drempel en je verbruiksdashboard wordt bijgewerkt. En dat allemaal zonder code te schrijven die steeds onze API bevraagt.

Webhooks dekken de events die aan de kant van Simbase plaatsvinden: inkomende sms'jes, IMEI-wijzigingen, wijzigingen in de SIM-status en bereikte gebruikslimieten.

Klaar om live te gaan? Registreer je webhook-endpoint in het dashboard, zodat Simbase weet waar het events moet afleveren.

Hoe Simbase webhooks gebruikt

Als er iets gebeurt in je account, doet Simbase een HTTPS POST naar de URL die je opgeeft, met een JSON-body die het event beschrijft. Je app leest de body, doet ermee wat je wilt en antwoordt met een 2xx-statuscode om te bevestigen dat het bericht is ontvangen.

Aan de ontvangende kant hoef je niets ingewikkelds te bouwen. De "URL die je opgeeft" kan een van deze zijn:

• Een no-code automatiseringsplatform zoals Zapier of Make.com

• Een chattool voor teams zoals Slack of Microsoft Teams, via hun ingebouwde incoming webhook-URL's (direct of met Zapier of Make.com ertussen)

• Een functie op je eigen backend, in elke programmeertaal

• Een externe sms-provider zoals Twilio of MessageBird, als je sms'jes wilt doorsturen naar gewone telefoonnummers

• Een serverless functie op AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions enzovoort

Als je ons een HTTPS-URL geeft, kunnen we er events naartoe sturen.

Webhook-events

Simbase ondersteunt de volgende eventtypes:

• Ontvangen sms'jes

• IMEI-wijziging

• Wijzigingen in de SIM-status

• Gebruikslimiet bereikt

Ontvangen sms'jes

SIM's met het profiel Black, Red of Green zitten in wat wij een gesloten sms-circuit noemen. Concreet: de SIM kan sms'jes sturen naar onze server op het korte nummer +55555 en sms'jes van onze server ontvangen, maar kan geen sms uitwisselen met andere telefoonnummers. Dat is bewust zo. Het is een beveiligingsmaatregel die je vloot onbereikbaar houdt vanaf het publieke sms-netwerk: niemand kan je apparaten een sms sturen, geen premium-sms-fraude kan je tegoed leegtrekken en sms kan niet worden misbruikt om je hardware aan te vallen.

SIM's met het profiel Blue, Yellow of Cyan hebben een MSISDN, dus externe nummers kunnen ze een sms sturen. Berichten die deze apparaten versturen blijven wel binnen Simbase en worden nooit naar een externe telefoon afgeleverd. De webhook werkt dus op elk profiel hetzelfde. Zie Sms voor de details per profiel.

Als je apparaat een sms naar +55555 stuurt, gebeuren er twee dingen:

1. Het bericht verschijnt in het Simbase-dashboard.

2. Als je een sms-webhook hebt geregistreerd, stuurt Simbase het volledige bericht via HTTPS door naar je endpoint.

Die tweede stap wordt door de meeste klanten onderschat. De payload bevat de berichttekst, de ICCID van de SIM, de apparaatnaam en een tijdstempel. Zodra die op je endpoint binnenkomt, kun je ermee doen wat je wilt.

Een paar echte voorbeelden van wat klanten met deze webhook bouwen:

• Stuur de sms-tekst door naar een Slack- of Microsoft Teams-kanaal, zodat het team berichten van apparaten live ziet. Handig voor asset trackers, verkoopautomaten, sensoren op afstand en elk apparaat dat via sms rapporteert.

• Stuur de payload naar Zapier of Make.com en start alles wat die platforms ondersteunen: loggen in Google Sheets, een e-mail sturen, een CRM bijwerken, een ticket aanmaken in Zendesk of Intercom, iets posten in Notion enzovoort. Zonder code.

• Stuur de sms door naar een extern telefoonnummer via Twilio, MessageBird of een andere sms-provider. Je apparaat stuurt een sms via Simbase, je webhook ontvangt die, je code stuurt de tekst door naar Twilio en Twilio levert hem af op een gewone mobiele telefoon. Zo bouwen klanten een eenrichtingsbrug van een afgeschermde IoT-vloot naar een normaal telefoonnummer, zonder de beveiliging van het gesloten circuit op te geven.

• Haal sensorwaarden of commando's uit de sms-tekst en sla ze op in je eigen database of in een time-series database zoals InfluxDB of TimescaleDB.

• Start een actie op de SIM zelf. Je endpoint ontvangt de sms, besluit dat "dit apparaat zich misdraagt" en roept de Simbase API aan om de SIM uit te schakelen.

Voor wie geen code schrijft, kort gezegd: de sms-webhook maakt van "er kwam een sms binnen op een SIM" iets als "Slack gaf een melding", "de spreadsheet is bijgewerkt", "het team kreeg een e-mail" of "er is een ticket geopend". Je hoeft niet te weten hoe sms-routering werkt. Je hoeft Simbase alleen de juiste URL te geven. Zie Sms.

JSON-body van de webhook

{
  "event": "sms",
  "iccid": "8900000000001234567",
  "timestamp": "2026-08-06 12:00:00",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

IMEI-wijziging

Elk apparaat heeft een IMEI (International Mobile Equipment Identity), een unieke code van 15 cijfers die vast in de hardware zit. Als je SIM in een ander apparaat wordt geplaatst, ziet het mobiele netwerk de nieuwe IMEI en meldt die. Simbase kan je endpoint daar direct over informeren.

Waarom dat belangrijk is, hangt af van je business. Bij asset tracking, logistiek of fleetmanagement is een onverwachte IMEI-wijziging een van de sterkste signalen dat een SIM uit het bedoelde apparaat is gehaald: door diefstal, sabotage of onderhoud dat misgaat. Voor OEM's die vooraf geprovisionde apparaten leveren, bevestigen IMEI-wijzigingen dat elke SIM in het juiste apparaat terecht is gekomen.

Wat klanten meestal met deze webhook doen:

• Het event naar Slack of e-mail sturen, zodat je operationele team ernaar kan kijken.

• Automatisch een ticket openen in je supporttool als de nieuwe IMEI niet bij een verwacht apparaat hoort.

• De SIM uitschakelen via de Simbase API als je beveiligingsbeleid onverwachte IMEI-wijzigingen als fraudesignaal ziet.

• De wijziging vastleggen in je assetdatabase, zodat je altijd weet welke SIM in welk apparaat zit, zonder handmatig bij te houden.

• Het event naar een SIEM of auditlog sturen voor compliance en forensisch onderzoek.

JSON-body van de webhook

{
  "event": "imei",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Wijzigingen in de SIM-status

Een SIM heeft een status die aangeeft of hij ingeschakeld of uitgeschakeld is. De status kan om verschillende redenen veranderen:

• Handmatig in- of uitschakelen via het dashboard of de API

• Automatische activering bij het eerste gebruik van de SIM

• Saldo op

• Incidenten zoals diefstal of vermoedelijke fraude

• Niet-toegestane IMEI-wijzigingen

Als de status verandert, stuurt Simbase de nieuwe status naar je webhook, zodat de rest van je stack kan reageren. Zie SIM-status.

Wat klanten meestal met dit event doen:

• Een intern CRM, ERP of assetdatabase synchroon houden met de echte status van elke SIM, zonder steeds de Simbase API te bevragen.

• Een melding in Slack of per e-mail krijgen zodra een SIM wordt uitgeschakeld, zodat support het weet voordat de klant belt.

• Facturatie automatisch starten als een SIM voor het eerst wordt geactiveerd, door het event via Zapier of je eigen backend naar Stripe, Chargebee of een eigen facturatiedienst te sturen.

• Verrassingen vroeg opvangen. Is een SIM uitgeschakeld zonder dat iemand in je team het verwachtte, behandel dat dan automatisch als incident.

JSON-body van de webhook

{
  "event": "sim_state",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Gebruikslimiet bereikt

Je kunt op elke SIM een maandelijkse limiet voor data of sms instellen. Gaat het verbruik over die limiet, dan schakelt Simbase de SIM automatisch uit en laat deze webhook de rest van je stack dat direct weten.

Limieten worden gecontroleerd wanneer verbruiksgegevens van de operator binnenkomen, niet in realtime. Een SIM kan dus iets boven de limiet uitkomen voordat hij wordt uitgeschakeld. Zie Gebruikslimieten voor waarom dat gebeurt en hoe je erop kunt budgetteren.

Zo zie je een apparaat dat zich vreemd gedraagt al vroeg. Een SIM die normaal 10 MB per maand gebruikt en ineens zijn limiet bereikt, probeert je meestal iets te vertellen: een firmwarebug, een wifi-fallback die misging, een apparaat dat in debugmodus is blijven staan, een OTA-update die uit de hand loopt of, in het ergste geval, een gestolen SIM die voor tethering wordt gebruikt.

Wat klanten meestal met dit event doen:

• Een melding naar Slack of e-mail sturen, zodat het team weet dat een SIM offline is voordat de klant belt

• Een incident openen in PagerDuty of Opsgenie bij deployments met hoge prioriteit

• Het apparaat controleren en daarna de SIM weer inschakelen of de limiet verhogen via de Simbase API

• Een Zapier- of Make.com-flow starten die de eigenaar van het apparaat informeert

• Het event loggen in een dashboard voor afwijkend verbruik, zodat je trends in je hele vloot op tijd ziet

JSON-body van de webhook

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

Zo ontvang je webhooks

In een paar stappen ontvang je eventmeldingen in je app:

1. Bepaal naar welke events je wilt luisteren en welke velden in de payload je echt nodig hebt.

2. Maak een HTTP(S)-endpoint om de events te ontvangen. Dat kan een route op je backend zijn, een serverless functie, een webhook-URL van Zapier of Make.com, een incoming webhook van Slack (met een kleine transformatie ervoor) of elke andere URL die POST-requests accepteert.

3. Parse de JSON-body aan jouw kant en geef een 2xx-statuscode terug. Voor Simbase telt alleen de statuscode, niet de response body.

4. Test het endpoint met een tool als Postman of curl. Wil je echte Simbase-events ontvangen terwijl je op je laptop ontwikkelt, dan werkt een tunneltool zoals ngrok of Cloudflare Tunnel goed.

5. Zet je endpoint live achter een publiek bereikbare HTTPS-URL.

6. Registreer die URL in het Simbase-dashboard onder Integrations → Webhooks.

7. Simbase stuurt een testevent naar je URL. Antwoordt je endpoint met een 2xx-code, dan wordt de webhook opgeslagen en ontvangt hij live events.

Specificaties

Methode

Alle calls van Simbase naar je webhook zijn HTTP POST-requests met een JSON-body.

Beveiliging

• Gebruik geen IP-filtering als beveiligingsmaatregel. Onze servers staan verspreid over de wereld en de publieke IP-adressen waarvandaan ze versturen veranderen in de loop van de tijd. Een IP-allowlist gaat dus op het slechtst denkbare moment stuk.

Veelgestelde vragen

Gerelateerd

• Sms: de berichten die de webhook voor ontvangen sms'jes doorstuurt, en hoe die per profiel verschillen

• Diefstalbeveiliging: koppel een SIM aan één IMEI, zodat een wijziging wordt geblokkeerd en niet alleen gemeld

• SIM-status: wat Ingeschakeld en Uitgeschakeld betekenen en wat ze verandert

• Gebruikslimieten: stel de limiet in die de verbruikswebhook activeert

• API-keys: maak een key aan en beperk die tot wat de integratie nodig heeft

• API: webhooks opvragen, aanmaken en verwijderen via code