Skip to main content

Work with system events

There are three ways you can access and trigger available events:

Data Streamer​

With the emnify Data Streamer, you can configure data streams to reflect events generated by the emnify system when your users perform billing-related updates, order SIMs, or perform other operations.

Using one of the many integrations provides you with complete network transparency to triage and resolve issues quickly and build your application or business logic based on the provided information. These integrations also provide insights for IoT remote monitoring and anomaly detection or detailed information about service usage (that is, data and SMS) and cost per device.

tip

See the Data Streamer documentation to learn more about its benefits and how to get started.

Manage event data streams in the Portal​

To manage your data streams, log in to your emnify Portal account. Then, navigate to the Data Streams section of the Integrations page.

If there are no data streams configured, the Data Streams panel displays all available connection types as tiles.

If you already have a data stream configured, the panel displays all existing streams, ordered by creation date (newest on the top). This list view can be used to gain an overview of the current states of different data streams.

Data streams are marked as Running are properly operating. Failed streams exhibit an Error status. Paused streams are marked as Paused.

The Details button allows you to inspect the configuration of the specific stream.

info

You can distinguish event data streams by checking if the Stream Type on a specific data stream is set to Stream events.

The Data Streamer can apply filtering for event data streams based on event types. Under Event Options, you can choose to Stream all events or Stream specific events only. Selecting the latter displays a searchable dropdown listing all event types available as filters.

tip

You can also create, update, and delete data streams using the Portal. Learn more in the Data Streamer usage documentation.

Event API​

The emnify REST API provides a variety of HTTP requests to integrate several emnify services into your application, including triggering and monitoring events.

The Event API specifically allows searching for recent events and supports various types of result filtering.

caution

For events, the emnify REST API uses a pull architecture, which means you're responsible for requesting updates and retrieving new events. If you prefer real-time updates, use the emnify Data Streamer.

Authentication​

To use the emnify API, you need to authenticate with an authentication token. emnify use JSON Web Tokens (JWTs) for the authentication tokens.

tip

The Getting Started guide in the emnify REST API Documentation provides step-by-step instructions for retrieving your token.

Specification and documentation​

The emnify API is based on the OpenAPI Specification 3.0 (OAS3). We also have interactive API documentation.

note

Prior OpenAPI knowledge isn't necessary for working with the emnify API. Nevertheless, understanding how an OpenAPI Specification is structured could help you navigate the documentation.

The Events Reference page in the emnify REST API Documentation provides details about the event structure and common elements you'll encounter while working with the Event API.

Retrieve events with the Event API​

The following entry points are available for retrieving a list of the events or event types available to your organization:

MethodEntry pointDescription
GET/api/v1/eventReturns the list of events, filtered, sorted, and paged according to query parameters.
GET/api/v1/event/typeProvides the list of event_types (lookup).

Using the following entry points, you can also list events for specific endpoints, SIMs, or users. These event lists can be filtered, sorted, and paged according to query parameters.

MethodEntry pointDescription
GET/api/v1/endpoint/{endpoint_id}/eventReturns the list of endpoint events.
GET/api/v1/sim/{sim_id}/eventReturns the list of SIM events.
GET/api/v1/user/{user_id}/eventReturns the list of user events.

emnify Portal​

There are several ways to view or trigger events within the emnify Portal.

Events in the Portal​

Here's where you can find event information in the Portal:

  • Dashboard: Overview of all event activity within your organization.
  • Connected Devices > Details > Events: List of triggered events for a particular device (also referred to as an "endpoint").
  • SIM Inventory > Details > Events: List of triggered events for a particular SIM card.
info

Any events triggered in the Portal shows API as the event source.

Available data for individual events​

No matter where you view events in the Portal, you'll have access to the following information for each event:

  • Severity: The event severity.
  • Date: When the event was triggered. By default, the Portal shows the relative date (for example, "a day ago," "15 days ago," "a month ago"). Pressing the clock icon shows an absolute date value in the MMMM dd, yyyy hh:mm a format.
  • Event Source: Which system triggered the event.
  • Event Type: Name of the triggered event (the description value in the Event Type Object). This field also indicates the network generation (4G, 5G, etc.) for specific events, like [PDP context lifecycles](/system-events/ event-types#data-connection-lifecycle).
  • Device: Name of the device impacted by the event (the name value from the Endpoint Object). This name often links to the device's entry on the Connected Devices page of the emnify Portal.
  • Operator: Which Mobile Network Operator (MNO) the device is currently roaming on (for example, Vodafone, AT&T). Only listed for relevant network events.
  • Country: The country where the MNO listed in the Operator field is providing the cellular service.
  • ID: A generated unique identifier for the event.
  • Description: What happened, why (in some cases), and any additional details associated with the event type.