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.

Nutzen Sie bereits Webhooks?Es gibt keine Beeinträchtigungen. Ältere Webhooks funktionieren auf absehbare Zeit weiterhin, erhalten jedoch keine neuen Funktionen mehr. Verwenden Sie für alle neuen Anwendungen unbedingt „Events“.

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 BEITRAG Anfrage.

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

Geht behutsam mit CDRs um„simcard.usage.cdr“ ist mit Abstand der am häufigsten auftretende Ereignistyp: Eine aktive SIM-Karte kann täglich zahlreiche Datensätze erzeugen. Ein Filter für „simcard“ oder „simcard.usage“ umfasst diesen Typ. Beziehen Sie CDRs nur dann ein, wenn Sie Nutzungsdaten tatsächlich speichern oder verarbeiten, und stellen Sie sicher, dass Ihr Endpunkt das Datenvolumen bewältigen kann.

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:

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

Wozu die einzelnen Felder auf dem Umschlag dienen:

  • Ereignistyp gibt an, um welches Ereignis es sich handelt und welche Felder daher in Veranstaltung.

  • event_id ist für diese Veranstaltung einzigartig und bleibt bei jedem erneuten Versuch gleich. Verwenden Sie diese Option, um Duplikate zu ignorieren.

  • Zeitstempel ist der Zeitpunkt, zu dem Simbase das Ereignis aufgezeichnet hat, in UTC (RFC 3339).

  • Korrelations-ID Verknüpft das Ereignis mit der Ursache. Geben Sie diese Angabe an, wenn Sie sich wegen eines Ereignisses an den Support wenden.

  • Kunden-ID ist Ihr Simbase-Konto.

Nur die Veranstaltung Die Teile unterscheiden sich je nach Typ. Zwei weitere Beispiele:

IMEI geändert

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

Nutzungsgrenze überschritten (Speicherverbrauch in Byte, Schwellenwert beträgt null (falls nicht festgelegt)

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

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

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

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

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

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

  5. Antworte schnell. Ihr Endpunkt sollte einen 2xx den Status festlegen, sobald die Anfrage eingeht, und die eigentliche Arbeit erst danach erledigen.

  6. Überprüfen Sie die Unterschrift bevor auf ein Ereignis reagiert wird. Siehe Sicherheit.

  7. 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-Zeitstempel und Webhook-Signatur, das zur Überprüfung der Anfrage verwendet wird

  • X-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_id Wiederholungen 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 Zeitstempel wenn die Reihenfolge eine Rolle spielt, beispielsweise bei Zustandsänderungen.

  • Was als Erfolg gilt: irgendein 2xx Statuscode.

  • Erneuter Versuch mit einer Wartezeit von bis zu 4 Stunden: Zeitüberschreitungen, 408, 429 und 5xx Antworten. A Wiederholungsintervall Der Header wird berücksichtigt.

  • Nicht erneut versucht: jeder andere Statuscode, einschließlich Weiterleitungen.

  • Sofort suspendiert: a 410 Nicht mehr verfügbar Die 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.

KundenbindungEreignisse werden 30 Tage lang gespeichert. Zustellversuche sind 15 Tage lang einsehbar.

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
  • 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 Veranstaltung Feld, 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_Zustand und neuer_Zustand Felder.

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

  1. Fügen Sie ein Ziel für dieselben Ereignistypen hinzu, das auf eine neue Route auf Ihrem Endpunkt verweist.

  2. Passen Sie Ihren Code an, um die neue Nutzlast einzulesen und die Signatur zu überprüfen.

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

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