Events: Echtzeit-Benachrichtigungen von deinen SIMs
Ereignisse informieren Ihre Systeme sofort, sobald auf Ihren Simbase-SIM-Karten etwas passiert. Ein Gerät sendet eine SMS, eine SIM-Karte wird in ein neues Gerät eingelegt, eine SIM-Karte wird deaktiviert, ein Nutzungslimit wird überschritten: Simbase sendet die Details innerhalb von Sekunden an eine von Ihnen gewählte URL, sodass Sie die API nie abfragen müssen, um dies festzustellen.
Ereignisse ersetzen die bisherigen Webhooks. Sie decken dieselben Anwendungsfälle ab und bieten zusätzlich einige Funktionen, die sich Kunden gewünscht haben: mehr Ereignistypen, eine zentrale Zieladresse für viele Ereignistypen, signierte Anfragen, die Sie überprüfen können, ein Zustellungsprotokoll und längere Wiederholungsversuche.
Sind Sie bereit für den Live-Betrieb? Ziel hinzufügen auf der Seite „Integrationen“ des Dashboards.
So funktionieren Veranstaltungen
Zwei Ideen decken alles ab:
Eine Veranstaltung ist ein Datensatz zu einem bestimmten Ereignis, zum Beispiel „SIM 8900…567 hat eine SMS gesendet“. Jedes Ereignis verfügt über einen Typ, eine eindeutige ID, einen Zeitstempel und die zu seinem Typ gehörenden Details.
Ein Reiseziel dorthin werden Ereignisse gesendet. Heute handelt es sich dabei um einen Webhook: eine HTTPS-URL, die jedes Ereignis als JSON empfängt
BEITRAGAnfrage.
Wenn ein Ereignis eintritt, sendet Simbase dieses an jeden Empfänger, dessen Filter mit dem Typ des Ereignisses übereinstimmt. Ihr Endpunkt antwortet mit einem 2xx Statuscode.
Die URL kann eine beliebige Adresse sein, die POST-Anfragen über HTTPS akzeptiert:
Eine No-Code-Automatisierungsplattform wie Zapier oder Make.com
Ein Tool für Team-Chats wie Slack oder Microsoft Teams (in der Regel mit Zapier oder Make.com als Zwischenstufe, um die Nachricht anzupassen)
Eine Route in Ihrem eigenen Backend, in einer beliebigen Sprache
Eine serverlose Funktion auf AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions und ähnlichen Plattformen
Was ist neu im Vergleich zu Webhooks?
Weitere Veranstaltungstypen. Zusätzlich zu den vier bisherigen Ereignissen stehen nun auch an eine SIM-Karte gesendete SMS sowie alle neuen Nutzungsdaten (CDR) zur Verfügung.
Ein Reiseziel, viele Veranstaltungen. Ein Webhook der alten Generation übertrug einen Ereignistyp. Der Filter eines Ziels kann beliebig viele Ereignistypen oder alle Ereignistypen umfassen.
Unterzeichnete Anträge. Jede Anfrage ist mit einer Signatur versehen, sodass Ihr Endpunkt überprüfen kann, ob sie tatsächlich von Simbase stammt und unterwegs nicht verändert wurde.
Doppelte Einträge sind ausgeschlossen. Jedes Ereignis hat eine eindeutige
event_iddie bei jedem Zustellversuch gleich bleibt.Längere Wiederholungsversuche. Fehlgeschlagene Zustellungen werden mit einer Wartezeit von bis zu 4 Stunden erneut versucht, anstatt nur drei Versuche zu unternehmen.
Lieferprotokoll. Sie können die Zustellversuche der letzten 15 Tage für jeden Empfänger einsehen, einschließlich der fehlgeschlagenen Zustellungen.
Polling als Ausweichlösung. Ereignisse werden 30 Tage lang gespeichert und können auch über die API abgerufen werden, ohne dass ein Ziel angegeben werden muss.
Veranstaltungstypen
Die Bezeichnungen für Veranstaltungstypen bestehen aus durch Punkte getrennten Teilen, die vom Allgemeinen zum Spezifischen verlaufen, wie zum Beispiel simcard.sms.mo. Ein Filter kann mit einem vollständigen Ereignistyp oder nur mit dem Anfang des Namens übereinstimmen, sodass ein Filter mehrere verwandte Ereignistypen gleichzeitig abdecken kann.
Bei SMS-Ereignissen gelten die üblichen Mobilfunkbedingungen. MO (vom Mobilgerät gesendet) ist eine SMS, die von der SIM-Karte vom Gerät an Simbase gesendet wird. MT (Mobile Terminated) ist eine SMS, die vom Dashboard oder über die API an das Gerät gesendet und auf der SIM-Karte empfangen wird.
| Veranstaltungstyp | Gesendet am |
|---|---|
| Ein Gerät sendet eine SMS von der SIM-Karte an Simbase (MO, Mobile Originated) |
| Über das Dashboard oder die API wird eine SMS an die SIM-Karte gesendet (MT, Mobile Terminated) |
| In einem Gerät mit einer anderen IMEI-Nummer wurde eine SIM-Karte erkannt |
| Eine SIM-Karte ist aktiviert |
| Eine SIM-Karte ist deaktiviert |
| Eine SIM-Karte überschreitet einen in ihren Nutzungsgrenzen festgelegten Schwellenwert |
| Für eine SIM-Karte wird ein neuer Nutzungsdatensatz (CDR) angelegt |
simcard.sms.mosimcard.sms.mtsimcard.security.imei_changedsimcard.state.enabledsimcard.state.disabledsimcard.usage.threshold_exceededsimcard.usage.cdr
Ereignisse filtern
Wenn Sie ein Ziel anlegen, legt dessen Filter fest, welche Daten es empfängt:
Ein einzelner Ereignistyp, wie
simcard.state.disabled, für „Sag mir Bescheid, wenn eine SIM-Karte offline geht“.Ein Präfix, wie
SIM-Karte.SMS, für jeden Veranstaltungstyp, der damit beginnt. In diesem Fall sind das sowohl MO- als auch MT-SMS.Alles: Lassen Sie das Filterfeld leer, um alle Ereignistypen zu erhalten.
Was Menschen mit Events schaffen
SMS von Geräten (MO): Gerätemeldungen an Slack oder Teams weiterleiten, sie über Zapier in einer Google-Tabelle protokollieren, Sensorwerte in Ihre Datenbank einlesen oder sie über Twilio an eine Telefonnummer weiterleiten. Siehe SMS.
SMS an Geräte (MT): überprüfen, ob ein Befehl oder eine Konfigurations-SMS an ein Gerät gesendet wurde, und ein Protokoll über die gesendeten Nachrichten führen.
IMEI geändert: Benachrichtigungen auslösen oder ein Ticket erstellen, wenn eine SIM-Karte in einem unerwarteten Gerät erkannt wird, oder sie über die API deaktivieren. Das Ereignis enthält den Diebstahlschutzstatus der SIM-Karte, sodass Sie wissen, ob die Änderung blockiert wurde.
SIM aktiviert oder deaktiviert: Halten Sie Ihr CRM oder Ihre Asset-Datenbank auf dem neuesten Stand, benachrichtigen Sie den Support, bevor der Kunde anruft, oder starten Sie die Abrechnung, sobald eine SIM-Karte aktiviert wird. Siehe SIM-Status.
Nutzungsgrenze überschritten: Ein außer Kontrolle geratenes Gerät frühzeitig erkennen, einen PagerDuty-Vorfall eröffnen oder den Gerätebesitzer benachrichtigen. Siehe Nutzungsbeschränkungen.
CDRs: Integrieren Sie die Stream-Nutzungsdaten in Ihr eigenes Abrechnungs- oder Analysesystem, anstatt sie zu exportieren.
So sieht eine Veranstaltung aus
Jede Anfrage hat dieselbe äußere Form, die Umschlag, wobei die Details zur Veranstaltung im Veranstaltung Feld. Hier ist eine von einem Gerät gesendete SMS:
Wozu die einzelnen Felder auf dem Umschlag dienen:
Ereignistypgibt an, um welches Ereignis es sich handelt und welche Felder daher inVeranstaltung.event_idist für diese Veranstaltung einzigartig und bleibt bei jedem erneuten Versuch gleich. Verwenden Sie diese Option, um Duplikate zu ignorieren.Zeitstempelist der Zeitpunkt, zu dem Simbase das Ereignis aufgezeichnet hat, in UTC (RFC 3339).Korrelations-IDVerknüpft das Ereignis mit der Ursache. Geben Sie diese Angabe an, wenn Sie sich wegen eines Ereignisses an den Support wenden.Kunden-IDist Ihr Simbase-Konto.
Nur die Veranstaltung Die Teile unterscheiden sich je nach Typ. Zwei weitere Beispiele:
IMEI geändert
Nutzungsgrenze überschritten (Speicherverbrauch in Byte, Schwellenwert beträgt null (falls nicht festgelegt)
Die anderen Typen folgen dem gleichen Muster. SIM-Statusereignisse enthalten die iccid. CDRs enthalten die Start- und Endzeit, den Typ, das Volumen und das Netz (MCC und MNC). Die vollständige Feldliste für jeden Typ findet sich in der API-Referenz.
Ein Ziel festlegen
Entscheiden Sie, was Sie brauchen. Welche Ereignistypen und welche Felder darin Sie verwenden werden. Fangen Sie klein an; Sie können den Filter später noch anpassen.
Eine HTTPS-URL abrufen die POST-Anfragen akzeptiert: eine Route in Ihrem Backend, eine serverlose Funktion oder eine Webhook-URL von Zapier oder Make.com. Sie muss über das öffentliche Internet erreichbar sein.
Fügen Sie das Ziel hinzu. In der Dashboard, öffnen Integrationen und fügen Sie ein neues Ziel hinzu. Geben Sie die URL ein, vergeben Sie einen Namen, den Sie wiedererkennen, und legen Sie die Filter zu den gewünschten Veranstaltungstypen.
Speichern Sie das Signaturgeheimnis. Das Dashboard zeigt ein Geheimnis an, das mit
whsec_. Es wird nur einmal angezeigt, bewahren Sie es daher an einem sicheren Ort auf, beispielsweise in Ihrem Passwort-Manager oder im Geheimnisspeicher Ihrer App.Antworte schnell. Ihr Endpunkt sollte einen
2xxden Status festlegen, sobald die Anfrage eingeht, und die eigentliche Arbeit erst danach erledigen.Überprüfen Sie die Unterschrift bevor auf ein Ereignis reagiert wird. Siehe Sicherheit.
Lieferprotokoll anzeigen bei den ersten paar Ereignissen, um zu überprüfen, ob sie ankommen und Ihr Endpunkt mit folgendem Antworttext antwortet:
2xx.
Sie können Ziele auch über die API, unter Verwendung eines API-Schlüssels mit den Integrationsbereichen.
Technische Daten
Methode und Kopfzeilen
Jede Übertragung erfolgt über HTTPS BEITRAG mit einem JSON-Body, der ausschließlich an öffentliche IP-Adressen gesendet wird. Jede Anfrage enthält folgende Header:
Webhook-ID,Webhook-ZeitstempelundWebhook-Signatur, das zur Überprüfung der Anfrage verwendet wirdX-Simbase-Integrations-ID, an den Empfänger, an den die Anfrage gesendet wurde
Sicherheit
Anfragen werden im Anschluss an das offene Verfahren unterzeichnet Standard-Webhooks Spezifikation. Simbase signiert jede Anfrage mit der whsec_ Geheimnis und speichert das Ergebnis in der Webhook-Signatur Header. Durch die Überprüfung lässt sich nachweisen, dass die Anfrage von Simbase stammt und nicht manipuliert wurde.
Am einfachsten ist es, eine der kostenlosen Optionen zu nutzen Standard-Webhook-Bibliotheken, verfügbar für die meisten Sprachen: Übergeben Sie den Rohtext des Request-Bodys, die Header und Ihr Geheimnis, und die Bibliothek erledigt den Rest, einschließlich der Ablehnung alter Anfragen. Die API-Referenz enthält außerdem ein kurzes Beispiel, wie man dies ohne Bibliothek überprüfen kann.
Zwei Dinge, die man beachten sollte:
Überprüfen Sie den Rohkörper. Überprüfen Sie die Signatur anhand des Textkörpers genau so, wie er eingegangen ist, bevor Ihr Framework das JSON-Datenformat analysiert oder umformatiert.
Verlassen Sie sich nicht auf IP-Zulassungslisten. Die Server von Simbase sind weltweit verteilt, und die Adressen, von denen aus sie Nachrichten versenden, ändern sich im Laufe der Zeit. Die Signatur dient als zuverlässige Überprüfung.
Wenn Sie Ereignisse an ein No-Code-Tool senden, das Signaturen nicht überprüfen kann, behandeln Sie die URL selbst als vertrauliche Information und geben Sie sie nicht weiter.
Wenn Ihr Server ein selbstsigniertes TLS-Zertifikat verwendet, können Sie die Zertifikatsüberprüfung für dieses Ziel deaktivieren.
Zustellung und erneute Zustellversuche
Mindestens einmal. Ein Ereignis kann mehrmals auftreten. Verwenden Sie
event_idWiederholungen zu ignorieren.Nicht immer in der richtigen Reihenfolge. Ereignisse können in einer anderen Reihenfolge angezeigt werden, als sie tatsächlich stattgefunden haben. Sortieren nach
Zeitstempelwenn die Reihenfolge eine Rolle spielt, beispielsweise bei Zustandsänderungen.Was als Erfolg gilt: irgendein
2xxStatuscode.Erneuter Versuch mit einer Wartezeit von bis zu 4 Stunden: Zeitüberschreitungen,
408,429und5xxAntworten. AWiederholungsintervallDer Header wird berücksichtigt.Nicht erneut versucht: jeder andere Statuscode, einschließlich Weiterleitungen.
Sofort suspendiert: a
410 Nicht mehr verfügbarDie Antwort setzt das Ziel aus.Nach 48 Stunden gesperrt: Ein Ziel, bei dem 48 Stunden lang ununterbrochen Fehler auftreten, wird gesperrt. Aktivieren Sie es über das Dashboard oder die API erneut, um wieder neue Ereignisse zu empfangen.
Umstellung von älteren Webhooks
Die bisherigen Webhooks funktionieren weiterhin, sodass Sie in Ihrem eigenen Tempo umsteigen können. Für jedes bisherige Ereignis gibt es eine direkte Entsprechung:
| Alter Webhook | Veranstaltungstyp |
|---|---|
Empfangene SMS ( |
|
IMEI-Änderung ( |
|
Änderung des SIM-Status ( |
|
Nutzungsgrenzen erreicht ( |
|
Empfangene SMS (
SMS)IMEI-Änderung (
IMEI)Änderung des SIM-Status (
sim_state)Nutzungsgrenzen erreicht (
Nutzungsbeschränkungen)
Was ändert sich bei der Nutzlast:
Die Details bewegen sich innerhalb eines
VeranstaltungFeld, das in den oben beschriebenen Umschlag eingesteckt ist.Zeitstempel liegen im RFC-3339-Format vor, in UTC, wie zum Beispiel
2026-11-13T09:30:12Z.Ein Zustandswechsel umfasst nun zwei Ereignistypen – einen für „aktiviert“ und einen für „deaktiviert“ – anstelle von
alter_Zustandundneuer_ZustandFelder.Die Datennutzung wird in Byte und nicht in MB angegeben.
Der Gerätename ist nicht angegeben. Suchen Sie ihn bei Bedarf anhand der ICCID.
Ein sicherer Weg zum Wechsel:
Fügen Sie ein Ziel für dieselben Ereignistypen hinzu, das auf eine neue Route auf Ihrem Endpunkt verweist.
Passen Sie Ihren Code an, um die neue Nutzlast einzulesen und die Signatur zu überprüfen.
Lassen Sie beide Systeme einige Tage lang parallel laufen und vergleichen Sie die Ergebnisse. Rechnen Sie damit, dass jede Änderung in diesem Zeitraum zweimal eintrifft, einmal pro System.
Löschen Sie den alten Webhook unter Integrationen → Webhooks.
Häufig gestellte Fragen
Nein. Ältere Webhooks funktionieren auf absehbare Zeit weiterhin, erhalten jedoch keine neuen Funktionen. Für neue Integrationen sollten „Events“ verwendet werden.
Die Zustellung erfolgt mindestens einmal, sodass ein erneuter Versuch eintreffen kann, nachdem Ihr Endpunkt den ersten Versuch bereits verarbeitet hat. Speichern Sie die `event_id` von Ereignissen, die du bereits bearbeitet hast, und überspringe alle, die du bereits gesehen hast.
Es gab entweder `410 Nicht mehr verfügbar` oder 48 Stunden lang ununterbrochen fehlgeschlagen ist. Beheben Sie das Problem am Endpunkt, überprüfen Sie das Zustellungsprotokoll auf den Fehler und aktivieren Sie das Ziel anschließend auf der Seite „Integrationen“ wieder. Ereignisse aus der Zeit, in der die Zustellung ausgesetzt war, werden nicht erneut gesendet, Sie können sie jedoch noch 30 Tage lang über die API abrufen.
Ja, indem man sie über die API. Abrufe werden auf Ihr API-Kontingent angerechnet, daher ist ein Ziel die bessere Wahl für alles, was live ist.
Ja. Legen Sie für jede URL ein Ziel an, jeweils mit eigenen Ereignistypen.
Nein. TLS wird zur Gewährleistung des Datenschutzes und einer sicheren Kommunikation erzwungen. Sie können jedoch weiterhin ein selbstsigniertes Zertifikat verwenden und die TLS-Zertifikatsüberprüfung auf der Empfängerseite deaktivieren.
Verwandte Themen
Webhooks (veraltet): die bisherige Methode zum Empfangen von Ereignissen, die weiterhin unterstützt wird
API-Schlüssel: Erstellen Sie einen Schlüssel mit den für die Verwaltung der Ziele erforderlichen Gültigkeitsbereichen
SMS: Die Botschaften hinter den SMS-Ereignissen und wie sie sich je nach Profil unterscheiden
Diebstahlschutz: Eine SIM-Karte an eine bestimmte IMEI-Nummer binden; dies wird bei Ereignissen zur Änderung der IMEI-Nummer gemeldet
SIM-Status: Was „Aktiviert“ und „Deaktiviert“ bedeuten und wodurch sie sich ändern
Nutzungsbeschränkungen: Schwellenwerte für Schwellenwert-Ereignisse festlegen
API: Ziele verwalten und Ereignisse programmgesteuert abfragen



