Een webhook is een bericht dat je app ontvangt op het moment dat er iets gebeurt, in plaats van steeds opnieuw te moeten vragen: „Is er al iets nieuws?”. Wanneer er zich een gebeurtenis voordoet in je Simbase-account, stuurt Simbase die gebeurtenis in realtime door naar een URL die jij beheert.

Zo integreer je Simbase in de rest van je stack. Er komt een sms binnen op een simkaart en je Slack-kanaal geeft een melding. Een apparaat wisselt van IMEI en je ticketsysteem opent een incident. Het maandelijkse dataverbruik overschrijdt een drempelwaarde en je gebruiksdashboard wordt bijgewerkt. Dit alles zonder code te schrijven die onze API opvraagt.

Webhooks hebben betrekking op de gebeurtenissen die zich aan de kant van Simbase voordoen: inkomende sms-berichten, wijzigingen in de IMEI, wijzigingen in de SIM-status, snelheidsbeperkingen en gebruiksdrempels.

Klaar om live te gaan? Registreer je webhook-eindpunt op het Dashboard, zodat Simbase weet waar de gebeurtenissen moeten worden weergegeven.

Hoe Simbase webhooks gebruikt

Wanneer er iets gebeurt op je account, verstuurt Simbase een HTTPS POST-verzoek naar de door jou opgegeven URL, met een JSON-body waarin de gebeurtenis wordt beschreven. Je app leest de body, verwerkt deze naar eigen inzicht en stuurt een antwoord terug met een 2xx-statuscode om te bevestigen dat het bericht is ontvangen.

Je hoeft aan de ontvangende kant niets ingewikkelds te bouwen. De „URL die je opgeeft“ kan een van de volgende zijn:

• Een automatiseringsplatform zonder programmeerkennis, zoals Zapier of Make.com

• Een tool voor teamchats zoals Slack of Microsoft Teams, waarbij gebruik wordt gemaakt van de ingebouwde URL’s voor inkomende webhooks (rechtstreeks of via Zapier of Make.com)

• Een functie in je eigen backend, in welke programmeertaal dan ook

• Een externe sms-provider zoals Twilio of MessageBird, als je sms-berichten wilt versturen naar openbare telefoonnummers

• Een serverloze functie op AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions, enz.

Als u ons een HTTPS-URL kunt geven, kunnen wij daar evenementen naartoe sturen.

Webhook-gebeurtenissen

Simbase ondersteunt de volgende soorten gebeurtenissen:

• Ontvangen sms-berichten

• Wijzigingen in het IMEI-nummer

• Wijziging van de SIM-status

• Beperking

• Het verbruik overschrijdt de drempelwaarde

Ontvangen sms-berichten

Simbase-simkaarten maken deel uit van wat wij een ‘gesloten sms-circuit’ noemen. Simpel gezegd: je simkaart kan sms’jes versturen naar onze server via het korte nummer +55555 en sms’jes ontvangen van onze server, maar kan geen sms’jes uitwisselen met enig ander telefoonnummer ter wereld. Dit is bewust zo ontworpen. Het is een beveiligingsmaatregel die ervoor zorgt dat uw apparaten niet bereikbaar zijn via het openbare SMS-netwerk, zodat niemand uw apparaten kan sms'en, er geen oplichting via betaaldiensten uw saldo kan leeghalen en SMS niet kan worden gebruikt als aanvalsvlak tegen uw hardware.

Je kunt natuurlijk nog steeds sms’jes versturen en ontvangen vanaf je apparaten. De berichten lopen alleen via Simbase in plaats van via het openbare mobiele netwerk. En dat is precies waar deze webhook zo krachtig is.

Wanneer je toestel een sms naar +55555 verstuurt, gebeuren er twee dingen:

1. Het bericht wordt weergegeven op het Simbase-dashboard.

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

Die tweede stap is het onderdeel dat de meeste klanten onderschatten. De payload bevat de berichttekst, het ICCID van de simkaart, de naam van het apparaat en een tijdstempel. Zodra die bij je eindpunt binnenkomt, kun je ermee doen wat je wilt.

Een paar concrete voorbeelden van wat mensen met deze webhook bouwen:

• Stuur de tekst van het sms-bericht door naar een Slack- of Microsoft Teams-kanaal, zodat het team de berichten van het apparaat in realtime kan zien. Handig voor asset-trackers, automaten, sensoren op afstand of elk ander apparaat dat via sms rapporteert.

• Stuur de gegevens door naar Zapier of Make.com en activeer alle functies die deze platforms ondersteunen: een logboek bijhouden in Google Sheets, een e-mail versturen, een CRM bijwerken, een Zendesk- of Intercom-ticket aanmaken, iets posten op Notion, enzovoort. Je hebt geen code nodig.

• Stuur het sms-bericht door naar een extern telefoonnummer via Twilio, MessageBird of een andere sms-provider. Uw apparaat verstuurt een sms via Simbase, uw webhook ontvangt deze, uw code stuurt de inhoud door naar Twilio en Twilio bezorgt deze aan een gewone mobiele telefoon. Zo bouwen klanten een eenrichtingsverbinding tussen een afgesloten IoT-netwerk en een normaal telefoonnummer, zonder de veiligheid van het gesloten circuit op te geven.

• Analyseer de inhoud van de sms op sensorwaarden of commando’s en sla deze op in je eigen database of in een tijdreeksdatabase zoals InfluxDB of TimescaleDB.

• Activeer een actie op de simkaart. Je eindpunt ontvangt het sms-bericht, concludeert dat „dit apparaat zich ongewoon gedraagt“ en roept de Simbase-API aan om de simkaart uit te schakelen, de snelheid te beperken of onder een ander beleid te plaatsen.

Voor lezers die geen code schrijven, komt het er kort gezegd op neer dat de SMS-webhook ervoor zorgt dat „er is een sms binnengekomen op een simkaart“ wordt omgezet in „Slack kreeg een melding“, „het spreadsheet is bijgewerkt“, „het team kreeg een e-mail“ of „er is een ticket aangemaakt“. Je hoeft niet te leren hoe SMS-routing werkt. Je hoeft alleen maar Simbase naar de juiste URL te verwijzen. Lees meer over SMS hier.

JSON-webhook-body

{
  "event": "sms",
  "iccid": "8912300000001234567",
  "timestamp": "2022-12-23 12:31:09",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

IMEI-wijziging

Elk apparaat heeft een IMEI (International Mobile Equipment Identity), een unieke 15-cijferige identificatiecode die in de hardware is ingebouwd. Wanneer uw simkaart in een ander apparaat wordt geplaatst, detecteert het mobiele netwerk de nieuwe IMEI en meldt dit. Simbase kan uw eindpunt hiervan op de hoogte stellen zodra dit gebeurt.

Waarom dit van belang is, hangt af van uw bedrijf. Voor het volgen van bedrijfsmiddelen, logistiek of wagenparkbeheer is een onverwachte wijziging van het IMEI-nummer een van de duidelijkste aanwijzingen dat een simkaart uit het daarvoor bestemde apparaat is verwijderd, hetzij door diefstal, knoeien of onderhoud dat uit de hand is gelopen. Voor OEM’s die vooraf geconfigureerde apparaten leveren, zijn IMEI-wijzigingen de manier om te controleren of elke simkaart in het juiste apparaat terecht is gekomen.

Wat mensen doorgaans met deze webhook doen:

• Deel het voorval via Slack of e-mail, zodat je operationele team het kan onderzoeken.

• Maak automatisch een ticket aan in je supporttool wanneer het nieuwe IMEI-nummer niet overeenkomt met een verwacht apparaat.

• Schakel de simkaart uit via de Simbase API als uw beveiligingsbeleid onverwachte IMEI-wijzigingen als een teken van fraude beschouwt.

• Registreer de wijziging in je activadatabase, zodat je altijd weet welke simkaart in welk apparaat zit, zonder dat je dit handmatig hoeft te controleren.

• Stuur de gebeurtenis door naar een SIEM of auditlogboek voor naleving en forensisch onderzoek.

JSON-webhook-body

{
  "event": "imei",
  "timestamp": "2022-12-23 12:34:07",
  "iccid": "8912300000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Wijzigingen in de SIM-status

Een simkaart heeft een status die aangeeft of deze momenteel is ingeschakeld, uitgeschakeld, opgeschort enzovoort. 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 simkaart

• Negatief saldo

• Voorvallen zoals diefstal of vermoedelijke fraude

• IMEI-wijzigingen die een beleid in werking stellen

Wanneer de status verandert, stuurt Simbase de nieuwe status door naar je webhook, zodat de rest van je stack hierop kan reageren. Lees meer over SIM-statussen hier.

Wat klanten doorgaans doen bij deze gelegenheid:

• Zorg ervoor dat een interne CRM-, ERP- of activadatabase altijd synchroon loopt met de actuele status van elke simkaart, zonder de Simbase-API te hoeven raadplegen.

• Ontvang een melding via Slack of e-mail zodra een simkaart wordt geblokkeerd, zodat de helpdesk hiervan op de hoogte is nog voordat de klant belt.

• Start de facturatieautomatisering zodra een simkaart voor het eerst wordt geactiveerd, door de gebeurtenis via Zapier of je eigen backend door te sturen naar Stripe, Chargebee of een aangepaste facturatiedienst.

• Signaleer onverwachte situaties in een vroeg stadium. Als een simkaart is geblokkeerd en niemand in je team dit had verwacht, beschouw dat dan automatisch als een incident.

JSON-webhook-body

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

Beperking

In het Simbase-dashboard kun je verkeersbeleidsregels instellen om de datasnelheid van een simkaart automatisch te beperken zodra het maandelijkse verbruik een door jou gekozen drempel overschrijdt. Wanneer de snelheid van een simkaart wordt beperkt, kan Simbase een webhook activeren, zodat je er niet pas achter komt via een gefrustreerde klant.

Een paar handige vervolgstappen zodra het evenement bij je eindpunt binnenkomt:

• Stuur de eigenaar van het apparaat een e-mail of sms met de volgende duidelijke boodschap: "Je apparaat is tot het einde van de maand beperkt tot 100 KB/s".

• Steek een kaart in je ondersteuningstool, zodat het team klaar is als er een klacht over een „trage verbinding“ binnenkomt.

• Werk het dashboard voor klanten bij, zodat de klant precies kan zien wanneer de snelheidsbegrenzer in werking is getreden.

• Start een upsell- of upgrade-traject als een klant steeds tegen de limiet aanloopt.

• Stuur de gebeurtenis naar Slack, zodat de technische afdeling in realtime de patronen in de beperking van de capaciteit binnen het hele netwerk kan volgen.

JSON-webhook-body

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

Het verbruik overschrijdt de drempelwaarde

Zelfs zonder een verkeersbeleid in te stellen, kun je een webhook laten afgaan wanneer het maandelijkse dataverbruik van een simkaart een vaste drempel overschrijdt.

Dit is een eenvoudige manier om een apparaat dat zich vreemd gedraagt in een vroeg stadium op te sporen. Een simkaart die normaal gesproken 10 MB per maand verbruikt en plotseling de grens van 100 MB overschrijdt, probeert je meestal iets te vertellen: een firmwarefout, een mislukte wifi-fallback, een apparaat dat in de debugmodus is blijven staan, een uit de hand gelopen OTA-update of, in het ergste geval, een gestolen simkaart die wordt gebruikt voor tethering.

Wat klanten meestal doen bij deze gelegenheid:

• Stuur een melding naar Slack of per e-mail wanneer een simkaart de ingestelde limiet overschrijdt,

• Maak een incident aan in PagerDuty of Opsgenie voor implementaties met hoge prioriteit.

• De SIM automatisch beperken of uitschakelen via de Simbase API.

• Activeer een Zapier- of Make.com-workflow die de eigenaar van het apparaat een melding stuurt voordat de rekening oploopt.

• Registreer de gebeurtenis in een dashboard voor afwijkingen in het gebruik, zodat je in de loop van de tijd trends binnen het hele wagenpark kunt signaleren.

JSON-webhook-inhoud wanneer het gebruik de 100 MB overschrijdt

{
  "event": "limit.100mb",
  "timestamp": "2022-12-23 13:13:24",
  "iccid": "8912300000001234567",
  "usageBytes": 104857600,
  "usageMegaBytes": 100,
  "deviceName": "Demo device"
}

Stappen om webhooks te ontvangen

In een paar stappen kun je evenementmeldingen in je app ontvangen:

1. Bepaal naar welke gebeurtenissen je wilt luisteren en welke velden in de payload voor jou echt van belang zijn.

2. Maak een HTTP(S)-eindpunt aan om de gebeurtenissen te ontvangen. Dit kan een route op je backend zijn, een serverloze functie, een Zapier-webhook-URL, een Make.com-webhook-URL, een inkomende Slack-webhook (met een kleine aanpassing vooraf), of een andere URL die POST-verzoeken accepteert.

3. Parseer de JSON-body aan jouw kant en retourneer een 2xx-statuscode. Voor Simbase is alleen de statuscode van belang, niet de inhoud van het antwoord.

4. Test het eindpunt met een tool zoals Postbode of curl. Als je tijdens het ontwikkelen op je laptop echte Simbase-gebeurtenissen wilt ontvangen, kun je het beste een tunneling-tool zoals ngrok of Cloudflare Tunnel gebruiken.

5. Plaats uw eindpunt achter een openbaar bereikbare HTTPS-URL.

6. Registreer die URL in de Simbase-dashboard onder ‘Integraties’.

7. Simbase stuurt een testgebeurtenis naar je URL. Als je eindpunt reageert met een 2xx-code, wordt de webhook opgeslagen en begint deze live gebeurtenissen te ontvangen.

Specificaties

Methode

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

Beveiliging

• Elk gesprek heeft een header met de naam x-simbase-requesttoken. Voor testoproepen is de waarde test-test-test-test-test. Gebruik deze header aan jouw kant om te controleren of het verzoek daadwerkelijk afkomstig is van Simbase, voordat je er iets mee doet.

• Gebruik IP-filtering niet als beveiligingsmaatregel. Onze servers staan verspreid over de hele wereld en de openbare IP-adressen waarmee ze gegevens verzenden, veranderen in de loop van de tijd, waardoor een lijst met toegestane IP-adressen op het slechtst mogelijke moment niet meer werkt.