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.

Gebruik je al webhooks?Er gaat niets kapot. Oude webhooks blijven voorlopig gewoon werken, maar er komen geen nieuwe functies bij. Zorg ervoor dat je voor alles wat nieuw is gebruikmaakt van Events.

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 POST verzoek.

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_id dat 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
  • simcard.sms.mo
  • simcard.sms.mt
  • simcard.security.imei_changed
  • simcard.state.enabled
  • simcard.state.disabled
  • simcard.usage.threshold_exceeded
  • simcard.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.

Wees niet te streng met CDR’ssimcard.usage.cdr is veruit het drukste type gebeurtenis: een actieve simkaart kan dagelijks vele records genereren. Een filter op simcard of simcard.usage omvat dit type. Neem CDR’s alleen op als je daadwerkelijk gebruiksrecords opslaat of verwerkt, en zorg ervoor dat je eindpunt het volume aankan.

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:

{
"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"
}
}

Waar elk veld op de envelop voor dient:

  • event_type geeft aan om welke gebeurtenis het gaat, en dus welke velden je kunt verwachten in evenement.

  • event_id is uniek voor dit voorval en blijft bij elke nieuwe poging hetzelfde. Gebruik dit om duplicaten te negeren.

  • tijdstempel is het tijdstip waarop Simbase de gebeurtenis heeft geregistreerd, in UTC (RFC 3339).

  • correlation_id brengt de gebeurtenis in verband met de oorzaak ervan. Vermeld dit wanneer je contact opneemt met de helpdesk over een gebeurtenis.

  • klant-id is je Simbase-account.

Alleen de evenement onderdelen verschillen per type. Nog twee voorbeelden:

IMEI gewijzigd

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

Gebruikslimiet overschreden (gebruik in bytes, drempelwaarde is null (indien niet ingesteld)

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

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

  1. Bepaal wat je nodig hebt. Welke soorten gebeurtenissen en welke velden daarin je gaat gebruiken. Begin klein; je kunt het filter later nog aanpassen.

  2. 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.

  3. 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.

  4. 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.

  5. Reageer snel. Je eindpunt moet een 2xx de status vaststellen zodra het verzoek binnenkomt, en daarna het eigenlijke werk doen.

  6. Controleer de handtekening voordat er op een gebeurtenis wordt gereageerd. Zie Beveiliging.

  7. 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-tijdstempel en webhook-handtekening, dat wordt gebruikt om het verzoek te verifiëren

  • X-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_id om herhalingen te negeren.

  • Niet altijd in volgorde. Gebeurtenissen kunnen in een andere volgorde worden weergegeven dan waarin ze hebben plaatsgevonden. Sorteren op tijdstempel wanneer de volgorde van belang is, bijvoorbeeld bij statuswijzigingen.

  • Wat telt als succes: welke dan ook 2xx statuscode.

  • Opnieuw geprobeerd met een wachttijd van maximaal 4 uur: time-outs, 408, 429 en 5xx reacties. A Retry-After De koptekst wordt in acht genomen.

  • Niet opnieuw geprobeerd: elke andere statuscode, inclusief omleidingen.

  • Met onmiddellijke ingang geschorst: a 410 Weg Door 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.

BehoudGebeurtenissen worden 30 dagen bewaard. Bezorgpogingen blijven 15 dagen zichtbaar.

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
  • 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 evenement veld, 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_status en nieuwe_toestand velden.

  • 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:

  1. Voeg een bestemming toe voor dezelfde soorten evenementen, die verwijst naar een nieuwe route op je eindpunt.

  2. Pas je code aan om de nieuwe payload in te lezen en de handtekening te verifiëren.

  3. 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.

  4. 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