Ein Webhook ist eine Nachricht, die Ihre App erhält, sobald etwas passiert, anstatt ständig nachfragen zu müssen: „Gibt es schon etwas Neues?“ Wenn in Ihrem Simbase-Konto ein Ereignis eintritt, sendet Simbase dieses Ereignis in Echtzeit an eine von Ihnen verwaltete URL.

So binden Sie Simbase in den Rest Ihrer Systemlandschaft ein: Eine SMS geht auf einer SIM-Karte ein, und Ihr Slack-Kanal wird benachrichtigt. Ein Gerät ändert seine IMEI, und Ihr Ticket-System eröffnet einen Vorfall. Das monatliche Datenvolumen überschreitet einen Schwellenwert, und Ihr Nutzungs-Dashboard wird aktualisiert. All dies, ohne Code schreiben zu müssen, der unsere API abfragt.

Webhooks decken die Ereignisse ab, die auf der Seite von Simbase stattfinden: eingehende SMS, IMEI-Änderungen, Änderungen des SIM-Status, Drosselung und Nutzungsschwellenwerte.

Sind Sie bereit für den Live-Betrieb? Registrieren Sie Ihren Webhook-Endpunkt im Dashboard, damit Simbase weiß, wohin Ereignisse gesendet werden sollen.

Wie Simbase Webhooks nutzt

Wenn auf Ihrem Konto etwas passiert, sendet Simbase einen HTTPS-POST-Request an die von Ihnen angegebene URL, wobei der JSON-Body das Ereignis beschreibt. Ihre App liest den Body, verarbeitet ihn nach Ihren Vorgaben und antwortet mit einem 2xx-Statuscode, um den Empfang der Nachricht zu bestätigen.

Auf der Empfängerseite müssen Sie keine aufwendigen Lösungen entwickeln. Die „von Ihnen angegebene URL“ kann eine der folgenden sein:

• Eine No-Code-Automatisierungsplattform wie Zapier oder Make.com

• Ein Team-Chat-Tool wie Slack oder Microsoft Teams, unter Verwendung der integrierten URLs für eingehende Webhooks (direkt oder über Zapier oder Make.com)

• Eine Funktion in Ihrem eigenen Backend, in einer beliebigen Sprache

• Ein externer SMS-Anbieter wie Twilio oder MessageBird, falls Sie SMS-Nachrichten an öffentliche Telefonnummern weiterleiten möchten

• Eine serverlose Funktion auf AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions usw.

Wenn Sie uns eine HTTPS-URL mitteilen, können wir Ereignisse an diese URL übermitteln.

Webhook-Ereignisse

Simbase unterstützt die folgenden Ereignistypen:

• Empfangene SMS-Nachrichten

• Änderungen der IMEI-Nummer

• Änderung des SIM-Status

• Drosselung

• Die Nutzung überschreitet den Schwellenwert

Empfangene SMS-Nachrichten

Simbase-SIM-Karten befinden sich in einem sogenannten geschlossenen SMS-Kreislauf. Einfach ausgedrückt: Ihre SIM-Karte kann SMS an unseren Server unter der Kurznummer +55555 senden und SMS von unserem Server empfangen, aber sie kann keine SMS mit anderen Telefonnummern weltweit austauschen. Dies ist beabsichtigt. Es handelt sich um eine Sicherheitsmaßnahme, die Ihre Flotte vom öffentlichen SMS-Netzwerk abschirmt, sodass niemand Ihre Geräte per SMS erreichen kann, keine Betrugsversuche über Premium-Tarife Ihr Guthaben aufbrauchen können und SMS nicht als Angriffsfläche gegen Ihre Hardware genutzt werden können.

Natürlich können Sie weiterhin SMS von Ihren Geräten aus senden und empfangen. Die Nachrichten werden lediglich über Simbase statt über das öffentliche Mobilfunknetz weitergeleitet. Und genau hier kommt die Stärke dieses Webhooks zum Tragen.

Wenn Ihr Gerät eine SMS an die Nummer +55555 sendet, passieren zwei Dinge:

1. Die Meldung wird auf dem Simbase-Dashboard angezeigt.

2. Wenn Sie einen SMS-Webhook registriert haben, leitet Simbase die vollständige Nachricht über HTTPS an Ihren Endpunkt weiter.

Dieser zweite Schritt wird von den meisten Kunden unterschätzt. Die Nutzlast enthält den Nachrichtentext, die ICCID der SIM-Karte, den Gerätenamen und einen Zeitstempel. Sobald diese Daten bei Ihrem Endpunkt eintreffen, können Sie damit machen, was Sie wollen.

Einige konkrete Beispiele dafür, was Nutzer mit diesem Webhook entwickeln:

• Leiten Sie den SMS-Text an einen Slack- oder Microsoft Teams-Kanal weiter, damit das Team die Gerätemeldungen in Echtzeit sieht. Nützlich für Asset-Tracker, Verkaufsautomaten, Fernsensoren oder jedes andere Gerät, das per SMS meldet.

• Leiten Sie die Daten an Zapier oder Make.com weiter und lösen Sie alle von diesen Plattformen unterstützten Aktionen aus: Protokollierung in Google Sheets, Versenden einer E-Mail, Aktualisieren eines CRM-Systems, Erstellen eines Zendesk- oder Intercom-Tickets, Veröffentlichen in Notion usw. Ganz ohne Programmierung.

• Leiten Sie die SMS über Twilio, MessageBird oder einen anderen SMS-Anbieter an eine externe Telefonnummer weiter. Ihr Gerät sendet eine SMS über Simbase, Ihr Webhook empfängt sie, Ihr Code leitet den Text an Twilio weiter, und Twilio übermittelt ihn an ein normales Mobiltelefon. Auf diese Weise bauen Kunden eine Einwegverbindung von einer abgeschotteten IoT-Flotte zu einer normalen Telefonnummer auf, ohne dabei auf die Sicherheit des geschlossenen Netzwerks verzichten zu müssen.

• Analysieren Sie den SMS-Text auf Sensorwerte oder Befehle und speichern Sie diese in Ihrer eigenen Datenbank oder einem Zeitreihenspeicher wie InfluxDB oder TimescaleDB.

• Lösen Sie eine Aktion auf der SIM-Karte aus. Ihr Endpunkt empfängt die SMS, stellt fest, dass „sich dieses Gerät auffällig verhält“, und ruft die Simbase-API auf, um die SIM-Karte zu deaktivieren, ihre Nutzung zu drosseln oder sie einer anderen Richtlinie zuzuordnen.

Für Leser, die keinen Code schreiben: Kurz gesagt funktioniert der SMS-Webhook so, dass er „eine auf einer SIM-Karte eingegangene SMS“ in „eine Benachrichtigung in Slack“, „die Aktualisierung der Tabelle“, „eine E-Mail an das Team“ oder „die Eröffnung eines Tickets“ umwandelt. Sie müssen nicht lernen, wie SMS-Routing funktioniert. Sie müssen lediglich Simbase auf die richtige URL verweisen. Erfahren Sie mehr über SMS hier.

JSON-Webhook-Inhalt

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

Änderung der IMEI-Nummer

Jedes Gerät verfügt über eine IMEI (International Mobile Equipment Identity), eine eindeutige 15-stellige Kennung, die fest in der Hardware verankert ist. Wenn Ihre SIM-Karte in ein anderes Gerät eingelegt wird, erkennt das Mobilfunknetz die neue IMEI und meldet diese. Simbase kann Ihren Endpunkt in dem Moment benachrichtigen, in dem dies geschieht.

Warum dies von Bedeutung ist, hängt von Ihrem Unternehmen ab. Bei der Bestandsverfolgung, in der Logistik oder im Flottenmanagement ist eine unerwartete Änderung der IMEI eines der deutlichsten Anzeichen dafür, dass eine SIM-Karte aus dem vorgesehenen Gerät entfernt wurde – sei es durch Diebstahl, Manipulation oder fehlgeschlagene Wartungsarbeiten. Für OEMs, die vorkonfigurierte Geräte ausliefern, sind IMEI-Änderungen der Weg, um sicherzustellen, dass jede SIM-Karte in dem Gerät gelandet ist, für das sie vorgesehen war.

Was Nutzer in der Regel mit diesem Webhook machen:

• Leite das Ereignis an Slack oder per E-Mail weiter, damit sich dein Betriebsteam darum kümmern kann.

• Eröffnen Sie automatisch ein Ticket in Ihrem Support-Tool, wenn die neue IMEI nicht mit einem erwarteten Gerät übereinstimmt.

• Deaktivieren Sie die SIM-Karte über die Simbase-API, falls Ihre Sicherheitsrichtlinie unerwartete IMEI-Änderungen als Betrugsindikator wertet.

• Erfassen Sie die Änderung in Ihrer Anlagen-Datenbank, damit Sie jederzeit wissen, welche SIM-Karte sich in welchem Gerät befindet, ohne dass ein manueller Abgleich erforderlich ist.

• Leiten Sie das Ereignis zur Einhaltung von Vorschriften und für forensische Untersuchungen an ein SIEM-System oder ein Audit-Protokoll weiter.

JSON-Webhook-Inhalt

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

Änderungen des SIM-Status

Eine SIM-Karte verfügt über einen Status, der angibt, ob sie derzeit aktiviert, deaktiviert, gesperrt ist usw.

Der Status kann sich aus verschiedenen Gründen ändern:

• Manuelle Aktivierung oder Deaktivierung über das Dashboard oder die API

• Automatische Aktivierung bei der ersten Nutzung der SIM-Karte

• Negativer Kontostand

• Vorfälle wie Diebstahl oder mutmaßlicher Betrug

• IMEI-Änderungen, die eine Richtlinie auslösen

Wenn sich der Status ändert, übermittelt Simbase den neuen Status an Ihren Webhook, damit der Rest Ihrer Infrastruktur darauf reagieren kann. Erfahren Sie mehr über SIM-Status hier.

Was Kunden bei diesem Anlass in der Regel tun:

• Halten Sie eine interne CRM-, ERP- oder Anlagendatenbank stets auf dem aktuellen Stand des tatsächlichen Status jeder SIM-Karte, ohne die Simbase-API abzufragen.

• Erhalten Sie eine Benachrichtigung über Slack oder per E-Mail, sobald eine SIM-Karte deaktiviert wird, damit der Support davon erfährt, bevor der Kunde anruft.

• Starten Sie die Abrechnungsautomatisierung, sobald eine SIM-Karte zum ersten Mal aktiviert wird, indem Sie das Ereignis über Zapier oder Ihr eigenes Backend an Stripe, Chargebee oder einen benutzerdefinierten Abrechnungsdienst übermitteln.

• Erkennen Sie Überraschungen frühzeitig. Wenn eine SIM-Karte deaktiviert wurde und niemand in Ihrem Team damit gerechnet hat, behandeln Sie dies automatisch als Vorfall.

JSON-Webhook-Inhalt

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

Drosselung

Im Simbase-Dashboard können Sie Datenverkehrsrichtlinien festlegen, um die Datenübertragungsgeschwindigkeit einer SIM-Karte automatisch zu drosseln, sobald deren monatliches Datenvolumen einen von Ihnen festgelegten Schwellenwert überschreitet. Wenn die Datenübertragungsgeschwindigkeit einer SIM-Karte gedrosselt wird, kann Simbase einen Webhook auslösen, sodass Sie nicht erst durch einen verärgerten Kunden davon erfahren.

Einige nützliche Folgemaßnahmen, sobald das Ereignis an Ihrem Endpunkt eintrifft:

• Senden Sie dem Gerätebesitzer per E-Mail oder SMS eine klare Nachricht: „Die Geschwindigkeit Ihres Geräts wird bis zum Monatsende auf 100 KB/s gedrosselt.“

• Stecken Sie eine Karte in Ihr Support-Tool, damit das Team bereit ist, wenn eine Beschwerde wegen einer „langsamen Verbindung“ eingeht.

• Aktualisieren Sie das kundenorientierte Dashboard, damit der Kunde genau sehen kann, wann die Drosselung begonnen hat.

• Lösen Sie einen Upselling- oder Tarifwechsel-Prozess aus, wenn ein Kunde immer wieder an die Obergrenze stößt.

• Sende das Ereignis an Slack, damit die Entwickler die Drosselungsmuster in der gesamten Flotte in Echtzeit verfolgen können.

JSON-Webhook-Inhalt

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

Die Nutzung überschreitet den Schwellenwert

Auch ohne Festlegung einer Datenverkehrsrichtlinie kann ein Webhook ausgelöst werden, sobald die monatliche Datennutzung einer SIM-Karte einen festgelegten Schwellenwert überschreitet.

Dies ist eine elegante Methode, um ein fehlerhaftes Gerät frühzeitig zu erkennen. Eine SIM-Karte, die normalerweise 10 MB pro Monat verbraucht und plötzlich die 100-MB-Marke überschreitet, will Ihnen in der Regel etwas mitteilen: einen Firmware-Fehler, einen fehlgeschlagenen WLAN-Fallback, ein Gerät, das im Debug-Modus belassen wurde, ein außer Kontrolle geratenes OTA-Update oder im schlimmsten Fall eine gestohlene SIM-Karte, die für Tethering genutzt wird.

Was Kunden bei dieser Veranstaltung üblicherweise tun:

• Eine Benachrichtigung an Slack oder per E-Mail senden, wenn eine SIM-Karte das festgelegte Limit überschreitet,

• Eröffnen Sie bei Deployments mit hoher Priorität einen Vorfall in PagerDuty oder Opsgenie.

• Die SIM-Karte über die Simbase-API automatisch drosseln oder deaktivieren.

• Lösen Sie einen Zapier- oder Make.com-Ablauf aus, der den Gerätebesitzer mit einer Benachrichtigung informiert, bevor die Rechnung steigt.

• Erfassen Sie das Ereignis in einem Dashboard für Nutzungsanomalien, damit Sie im Zeitverlauf flottenweite Trends erkennen können.

JSON-Webhook-Inhalt, wenn die Nutzung 100 MB überschreitet

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

Schritte zum Empfangen von Webhooks

In wenigen Schritten können Sie in Ihrer App Ereignisbenachrichtigungen erhalten:

1. Entscheiden Sie, welche Ereignisse Sie überwachen möchten und welche Felder in der Nutzlast für Sie tatsächlich von Bedeutung sind.

2. Erstellen Sie einen HTTP(S)-Endpunkt, um die Ereignisse zu empfangen. Dies kann eine Route in Ihrem Backend, eine serverlose Funktion, eine Zapier-Webhook-URL, eine Make.com-Webhook-URL, ein eingehender Slack-Webhook (mit einer kleinen Vorverarbeitung) oder jede andere URL sein, die POST-Anfragen akzeptiert.

3. Analysieren Sie den JSON-Body auf Ihrer Seite und geben Sie einen 2xx-Statuscode zurück. Für Simbase ist nur der Statuscode von Bedeutung, nicht der Antworttext.

4. Testen Sie den Endpunkt mit einem Tool wie Postbote oder curl. Wenn Sie während der Entwicklung auf Ihrem Laptop echte Simbase-Ereignisse empfangen möchten, eignet sich ein Tunneling-Tool wie ngrok oder Cloudflare Tunnel gut.

5. Stellen Sie Ihren Endpunkt hinter einer öffentlich erreichbaren HTTPS-URL bereit.

6. Registrieren Sie diese URL in der Simbase-Dashboard unter „Integrationen“.

7. Simbase sendet ein Testereignis an Ihre URL. Wenn Ihr Endpunkt mit einem 2xx-Code antwortet, wird der Webhook gespeichert und beginnt, Live-Ereignisse zu empfangen.

Technische Daten

Verfahren

Alle Aufrufe von Simbase an Ihren Webhook sind HTTP-POST-Anfragen mit einem JSON-Body.

Sicherheit

• Jeder Aufruf enthält einen Header mit dem Namen x-simbase-requesttoken. Bei Testanrufen beträgt der Wert Test-Test-Test-Test-Test. Verwenden Sie diesen Header auf Ihrer Seite, um zu überprüfen, ob die Anfrage tatsächlich von Simbase stammt, bevor Sie darauf reagieren.

• Verwenden Sie IP-Filterung nicht als Sicherheitsmaßnahme. Unsere Server sind weltweit verteilt, und die öffentlichen IP-Adressen, von denen aus sie Daten senden, ändern sich im Laufe der Zeit, sodass eine IP-Whitelist im ungünstigsten Moment versagen wird.