Events: realtime meldingen van je SIM's
Gebeurtenissen geven uw systemen direct door wanneer er iets gebeurt op uw Simbase-simkaarten. Een apparaat verstuurt een sms, een simkaart wordt in een nieuw apparaat geplaatst, een simkaart wordt geblokkeerd, een gebruikslimiet wordt overschreden: Simbase stuurt de gegevens binnen enkele seconden naar een door u gekozen URL, zodat u nooit zelf de API hoeft te raadplegen om dit te achterhalen.
Gebeurtenissen vervangen de oude webhooks. Ze zijn geschikt voor dezelfde situaties en bieden bovendien een aantal extra functies waar klanten om hebben gevraagd: meer soorten gebeurtenissen, één bestemming voor meerdere soorten gebeurtenissen, ondertekende verzoeken die je kunt verifiëren, een afleverlogboek en langere herpogingen.
Klaar om live te gaan? Een bestemming toevoegen op de pagina ‘Integraties’ van het dashboard.
Hoe evenementen werken
Twee ideeën omvatten alles:
Een evenement is een registratie van een gebeurtenis, zoals „SIM 8900…567 heeft een sms verzonden”. Elke gebeurtenis heeft een type, een unieke ID, een tijdstempel en de details die bij dat type horen.
Een bestemming is waar gebeurtenissen naartoe worden gestuurd. Tegenwoordig is dat een webhook: een HTTPS-URL die elke gebeurtenis als JSON ontvangt
POSTverzoek.
Wanneer er een gebeurtenis plaatsvindt, stuurt Simbase deze naar elke bestemming waarvan het filter overeenkomt met het type van de gebeurtenis. Je eindpunt antwoordt met een 2xx statuscode.
De URL kan alles zijn wat een POST-verzoek via HTTPS accepteert:
Een automatiseringsplatform zonder code, zoals Zapier of Make.com
Een tool voor teamchats zoals Slack of Microsoft Teams (meestal met Zapier of Make.com ertussen om het bericht aan te passen)
Een route op je eigen backend, in welke taal dan ook
Een serverloze functie op AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions en dergelijke
Wat is er nieuw ten opzichte van webhooks?
Meer soorten evenementen. Naast de vier bestaande gebeurtenissen zijn nu ook SMS-berichten die naar een simkaart zijn verzonden en alle nieuwe gebruiksgegevens (CDR) beschikbaar.
Eén bestemming, talrijke evenementen. Een verouderde webhook ondersteunde één type gebeurtenis. Het filter van een bestemming kan zoveel gebeurtenistypen bevatten als je wilt, of alle gebeurtenistypen.
Ondertekende verzoeken. Elk verzoek is voorzien van een handtekening, zodat je eindpunt kan controleren of het daadwerkelijk afkomstig is van Simbase en onderweg niet is gewijzigd.
Veilig tegen dubbele invoer. Elk evenement heeft een unieke
event_iddat bij elke bezorgpoging hetzelfde blijft.Langere herhalingspogingen. Mislukte leveringen worden met een backoff-interval gedurende maximaal 4 uur opnieuw geprobeerd, in plaats van drie pogingen.
Leveringsoverzicht. Je kunt de bezorgpogingen van de afgelopen 15 dagen voor elke bestemming bekijken, inclusief de mislukte pogingen.
Stemmen als noodoplossing. Gebeurtenissen worden 30 dagen bewaard en kunnen ook via de API worden opgevraagd, zonder bestemming.
Soorten evenementen
De namen van evenementtypes bestaan uit onderdelen die door punten worden gescheiden, van algemeen naar specifiek, zoals simkaart.sms.mo. Een filter kan overeenkomen met een volledig evenementtype of alleen met het begin van de naam, zodat één filter meerdere verwante evenementtypes tegelijk kan omvatten.
Bij SMS-evenementen wordt gebruikgemaakt van de standaardvoorwaarden voor mobiele telefonie. MO (afkomstig van een mobiel apparaat) is een sms die door de simkaart wordt verzonden, vanaf het apparaat naar Simbase. MT (mobiel ontvangen) is een sms die vanaf het dashboard of via de API naar de simkaart van het apparaat wordt verzonden.
| Soort evenement | Verzonden op |
|---|---|
| Een apparaat verstuurt een sms vanaf de simkaart naar Simbase (MO, ‘mobile originated’) |
| Er wordt een sms naar de simkaart verzonden, via het dashboard of de API (MT, mobile terminated) |
| Er is een simkaart gedetecteerd in een apparaat met een ander IMEI-nummer |
| Een simkaart is geactiveerd |
| Een simkaart is uitgeschakeld |
| Een simkaart overschrijdt een drempelwaarde die is vastgesteld in de gebruikslimieten |
| Er wordt een nieuw gebruiksrecord (CDR) aangemaakt voor een simkaart |
simcard.sms.mosimcard.sms.mtsimcard.security.imei_changedsimcard.state.enabledsimcard.state.disabledsimcard.usage.threshold_exceededsimcard.usage.cdr
Gebeurtenissen filteren
Wanneer je een bestemming aanmaakt, bepaalt het filter van die bestemming wat er naar die bestemming wordt gestuurd:
Eén type gebeurtenis, zoals
simkaart.status.uitgeschakeld, voor "laat me weten wanneer een simkaart offline gaat".Een voorvoegsel, zoals
simkaart.sms, voor elk type gebeurtenis dat daarmee begint. In dit geval zijn dat zowel MO- als MT-sms’jes.Alles: laat het filter leeg om alle soorten gebeurtenissen te ontvangen.
Wat mensen met Events maken
SMS-berichten vanaf apparaten (MO): stuur apparaatberichten door naar Slack of Teams, registreer ze via Zapier in een Google-spreadsheet, voer sensorwaarden in je database in of stuur ze via Twilio door naar een telefoonnummer. Zie SMS.
SMS naar apparaten (MT): controleren of er een opdracht of configuratie-SMS naar een apparaat is verzonden, en een logboek bijhouden van wat er is verzonden.
IMEI gewijzigd: waarschuwingen genereren of een ticket aanmaken wanneer een simkaart in een onverwacht apparaat wordt gedetecteerd, of deze via de API uitschakelen. De gebeurtenis bevat de status van de diefstalbeveiliging van de simkaart, zodat u weet of de wijziging is geblokkeerd.
SIM ingeschakeld of uitgeschakeld: Houd je CRM- of assetdatabase gesynchroniseerd, breng de helpdesk op de hoogte voordat de klant belt, of start de facturering zodra een simkaart actief wordt. Zie SIM-status.
Gebruikslimiet overschreden: een uit de hand gelopen apparaat tijdig opsporen, een PagerDuty-incident aanmaken of de eigenaar van het apparaat op de hoogte brengen. Zie Gebruiksbeperkingen.
CDR's: integreer het streamgebruik in uw eigen facturerings- of analysesysteem in plaats van het te exporteren.
Hoe zo’n evenement eruitziet
Elk verzoek heeft dezelfde uiterlijke vorm, de envelop, met de details van het evenement in de evenement veld. Hier is een sms die door een apparaat is verzonden:
Waar elk veld op de envelop voor dient:
event_typegeeft aan om welke gebeurtenis het gaat, en dus welke velden je kunt verwachten inevenement.event_idis uniek voor dit voorval en blijft bij elke nieuwe poging hetzelfde. Gebruik dit om duplicaten te negeren.tijdstempelis het tijdstip waarop Simbase de gebeurtenis heeft geregistreerd, in UTC (RFC 3339).correlation_idbrengt de gebeurtenis in verband met de oorzaak ervan. Vermeld dit wanneer je contact opneemt met de helpdesk over een gebeurtenis.klant-idis je Simbase-account.
Alleen de evenement onderdelen verschillen per type. Nog twee voorbeelden:
IMEI gewijzigd
Gebruikslimiet overschreden (gebruik in bytes, drempelwaarde is null (indien niet ingesteld)
De andere typen volgen hetzelfde patroon. SIM-statusgebeurtenissen bevatten de iccid. CDR’s bevatten de begin- en eindtijd, het type, het volume en het netwerk (MCC en MNC). De volledige lijst met velden voor elk type staat in de API-referentie.
Een bestemming instellen
Bepaal wat je nodig hebt. Welke soorten gebeurtenissen en welke velden daarin je gaat gebruiken. Begin klein; je kunt het filter later nog aanpassen.
Een HTTPS-URL opvragen die POST-verzoeken accepteert: een route in je backend, een serverloze functie of een webhook-URL van Zapier of Make.com. Deze moet bereikbaar zijn via het openbare internet.
Voer de bestemming in. In de dashboard, open Integraties en voeg een nieuwe bestemming toe. Voer de URL in, geef deze een herkenbare naam en stel de Filter naar de gewenste evenementsoorten.
Sla het ondertekeningsgeheim op. Op het dashboard wordt een geheim weergegeven dat begint met
whsec_. Het wordt maar één keer weergegeven, dus bewaar het op een veilige plek, zoals je wachtwoordbeheerder of de geheime gegevensopslag van je app.Reageer snel. Je eindpunt moet een
2xxde status vaststellen zodra het verzoek binnenkomt, en daarna het eigenlijke werk doen.Controleer de handtekening voordat er op een gebeurtenis wordt gereageerd. Zie Beveiliging.
Bekijk het leveringsoverzicht bij de eerste paar gebeurtenissen, om te controleren of ze aankomen en of je eindpunt reageert met
2xx.
Je kunt bestemmingen ook aanmaken en beheren via de API, met behulp van een API-sleutel met de integratiescopes.
Technische gegevens
Methode en kopteksten
Elke verzending verloopt via HTTPS POST met een JSON-body, die uitsluitend naar openbare IP-adressen wordt verzonden. Elk verzoek bevat de volgende headers:
webhook-id,webhook-tijdstempelenwebhook-handtekening, dat wordt gebruikt om het verzoek te verifiërenX-Simbase-Integratie-ID, de bestemming waarnaar het verzoek is verzonden
Beveiliging
Verzoeken worden ondertekend na de open Standaard webhooks specificatie. Simbase ondertekent elk verzoek met de whsec_ geheim en slaat het resultaat op in de webhook-handtekening header. Door deze te controleren, kun je vaststellen dat het verzoek afkomstig was van Simbase en niet is gemanipuleerd.
De makkelijkste manier is een van de gratis Standaardbibliotheken voor webhooks, beschikbaar voor de meeste talen: geef de onbewerkte verzoektekst, de headers en je geheim door, en de bibliotheek doet de rest, inclusief het afwijzen van oude verzoeken. De API-referentie bevat ook een kort voorbeeld om dit zonder bibliotheek te controleren.
Twee dingen om in gedachten te houden:
Controleer de ruwe carrosserie. Controleer of de handtekening precies overeenkomt met de inhoud zoals deze is ontvangen, voordat je framework de JSON parseert of opnieuw opmaakt.
Vertrouw niet op IP-toegangslijsten. De servers van Simbase staan verspreid over de hele wereld en de adressen van waaruit ze berichten versturen, veranderen in de loop van de tijd. De handtekening vormt de betrouwbare controle.
Als je gebeurtenissen verstuurt naar een no-code-tool die handtekeningen niet kan controleren, beschouw de URL dan als een geheim en deel deze niet.
Als je server een zelfondertekend TLS-certificaat gebruikt, kun je de certificaatcontrole voor die bestemming uitschakelen.
Levering en herhalingspogingen
Ten minste één keer. Een gebeurtenis kan meer dan eens plaatsvinden. Gebruik
event_idom herhalingen te negeren.Niet altijd in volgorde. Gebeurtenissen kunnen in een andere volgorde worden weergegeven dan waarin ze hebben plaatsgevonden. Sorteren op
tijdstempelwanneer de volgorde van belang is, bijvoorbeeld bij statuswijzigingen.Wat telt als succes: welke dan ook
2xxstatuscode.Opnieuw geprobeerd met een wachttijd van maximaal 4 uur: time-outs,
408,429en5xxreacties. ARetry-AfterDe koptekst wordt in acht genomen.Niet opnieuw geprobeerd: elke andere statuscode, inclusief omleidingen.
Met onmiddellijke ingang geschorst: a
410 WegDoor deze reactie wordt de bestemming opgeschort.Na 48 uur geschorst: Een bestemming die 48 uur achter elkaar mislukt, wordt opgeschort. Schakel deze opnieuw in via het dashboard of de API om weer nieuwe gebeurtenissen te ontvangen.
Overstappen van verouderde webhooks
Oude webhooks blijven gewoon werken, zodat je het in je eigen tempo kunt aanpakken. Elke oude gebeurtenis heeft een direct equivalent:
| Oude webhook | Soort evenement |
|---|---|
Ontvangen sms ( |
|
IMEI wijzigen ( |
|
Wijziging van de SIM-status ( |
|
Gebruikslimieten bereikt ( |
|
Ontvangen sms (
sms)IMEI wijzigen (
IMEI)Wijziging van de SIM-status (
sim_state)Gebruikslimieten bereikt (
gebruikslimieten)
Welke wijzigingen zijn er in de lading:
De details bewegen zich binnen een
evenementveld, verpakt in de hierboven beschreven envelop.Tijdstempels worden weergegeven in het RFC 3339-formaat, in UTC, zoals
2026-11-13T09:30:12Z.Een statuswijziging bestaat nu uit twee soorten gebeurtenissen: één voor ‘ingeschakeld’ en één voor ‘uitgeschakeld’, in plaats van
oude_statusennieuwe_toestandvelden.Het dataverbruik wordt uitgedrukt in bytes in plaats van MB.
De naam van het apparaat staat er niet bij. Zoek het op aan de hand van het ICCID als je het nodig hebt.
Een veilige manier om over te stappen:
Voeg een bestemming toe voor dezelfde soorten evenementen, die verwijst naar een nieuwe route op je eindpunt.
Pas je code aan om de nieuwe payload in te lezen en de handtekening te verifiëren.
Laat beide een paar dagen naast elkaar draaien en vergelijk ze. Reken erop dat elke wijziging in deze periode twee keer binnenkomt, één keer per systeem.
Verwijder de verouderde webhook onder Integraties → Webhooks.
Veelgestelde vragen
Nee. Oude webhooks blijven voorlopig gewoon werken, maar krijgen geen nieuwe functies meer. Voor nieuwe integraties moet gebruik worden gemaakt van Events.
Er vindt ten minste één levering plaats, dus een nieuwe poging kan binnenkomen nadat je eindpunt de eerste poging al heeft verwerkt. Sla de `event_id` van de evenementen die je hebt afgehandeld, en sla de evenementen over die je al hebt gezien.
Het gaf ofwel `410 Weg` of 48 uur achter elkaar is mislukt. Los het probleem met het eindpunt op, controleer het verzendlogboek op de fout en schakel de bestemming vervolgens opnieuw in op de pagina ‘Integraties’. Gebeurtenissen die plaatsvonden terwijl de bestemming was opgeschort, worden niet opnieuw verzonden, maar je kunt ze nog wel 30 dagen lang via de API inzien.
Ja, door ze te peilen via de API. Het opvragen van gegevens telt mee voor je API-quotum, dus een bestemming is de betere keuze voor alles wat live is.
Ja. Maak voor elke URL een bestemming aan, elk met zijn eigen gebeurtenistypen.
Nee. TLS wordt verplicht gesteld om de gegevensprivacy en veilige communicatie te waarborgen. Je kunt echter nog steeds een zelfondertekend certificaat gebruiken en de TLS-certificaatverificatie aan de ontvangende kant uitschakelen.
Gerelateerd
Webhooks (verouderd): de vroegere manier om gebeurtenissen te ontvangen, wordt nog steeds ondersteund
API-sleutels: maak een sleutel aan met de reikwijdtes die nodig zijn om bestemmingen te beheren
SMS: de boodschappen achter de sms-gebeurtenissen, en hoe deze per profiel verschillen
Diefstalbeveiliging: een simkaart aan één IMEI-nummer koppelen, gemeld bij gebeurtenissen waarbij het IMEI-nummer is gewijzigd
SIM-status: wat ‘Ingeschakeld’ en ‘Uitgeschakeld’ betekenen en waardoor deze statussen veranderen
Gebruiksbeperkingen: stel de drempelwaarden in achter drempelgebeurtenissen
API: bestemmingen beheren en gebeurtenissen programmatisch opvragen



