Events Endpoints

Events Endpoints

When integrating Netify into a user interface (UI), it is often necessary to present the end user with event information. The following endpoints provide information on the events supported by Netify Informatics:

Data Description
Events Catalog The list of supported applications.
Events Status The current status of active events.
Events Log The log of event activities.
Events Subscriptions The event subscription handler.

Quick Reference

You can find links to information on authentication, response codes, and other developer topics in the menu. The Event API endpoints require an agent or site identifier (UUID or serial number) along with an access token or vendor API key. 
# Example curl request: active devices with VPN activity
curl -g -H 'x-net-uuid: {agent_identifier}' \
  -H 'x-api-key: {vendor_api_key}' \
  'https://informatics.netify.ai/api/v1/events/status?filter_events=["vpn_detection"]'

Events Catalog API

Endpoint https://informatics.netify.ai/api/v1/events/catalog

The Events Catalog provides a list of all the events supported by the Netify Agent.

You can use the filter_events parameter to limit the events returned in the API call. The Quick Reference example above provides an example for filtering on only the VPN Detection event.

ID and Tag

You can identify an event by an ID number (e.g., 12) or tag (e.g., tor_detection).

Label

The label is the name an end user would typically use to identify the event.

Introduced

The Netify Agent version where the event was introduced.

Deprecated

The Netify Agent version where the event was deprecated.

Event Catalog - JSON Example

{
    "id": 12,
    "tag": "tor_detection",
    "label": "Tor Detection"
    "introduced": "3.0.5",
    "deprecated": ""
},

Events Status API

Endpoint https://informatics.netify.ai/api/v1/events/status

The Events Status API provides a list of all active events on the network. For example, you can fetch a list of all devices that have recently connected to the Tor Network.

You can use the filter_events parameter to limit the events returned in the API call. The Quick Reference example above provides an example for filtering on only the VPN Detection event.

Key

The event key. Please see the Events Overview for details.

Score

The score provides the risk level of the event.

Score Description
0 Informational
1-25 Low Risk
26-50 Medium Risk
51-75 High Risk
76-100 Critical Risk

Details

Additional information on the event. For example, the VPN Detection event includes information on the MAC address as well as the VPN protocol.

Event Status - JSON Example

{
    "key": "vpn_detection|c2:0d:07:16:cd:bc|79",
    "event": {
        "id": 8,
        "tag": "vpn_detection",
        "label": "VPN Detection"
    },
    "score": 60,
    "details": {
        "mac": {
            "address": "c2:0d:07:16:cd:bc",
            "discovery_label": "Pixel 7"
        },
        "protocol": {
            "id": 79,
            "name": "IPsec"
        }
    },
    "first_seen": 1765359475,
    "last_seen": 1766407466
},

Events Log API

Endpoint https://informatics.netify.ai/api/v1/events/log

The Events Log API provides a list of log events. For example, the Device Discovery system will send a log event within the first minute of discovering a new MAC address on the network. After a few more minutes (or hours) of gathering information, it is very common to see an updated device identification log event.

ID

The unique event log ID

Key

The event key. Please see the Events Overview for details.

Event

The event object that comes from the Event Catalog API.

Score

The score provides the risk level of the event.

Score Description
0 Informational
1-25 Low Risk
26-50 Medium Risk
51-75 High Risk
76-100 Critical Risk

Type

The event type: new or updated.

Title

A title intended for end users.

Description

A short description intended for end users.

Details

Additional information on the event. In our VPN Detection event, information on the MAC address as well as the VPN protocol are provided.

Event Log - JSON Example

{
    "id": 21232,
    "key": "device_discovery|8a:01:58:9c:48:fe",
    "event": {
        "id": 2,
        "tag": "device_discovery",
        "label": "Device Discovery"
    },
    "score": 0,
    "type": "new",
    "title": "New device detected",
    "description": "New device 8a:01:58:9c:48:fe discovered",
    "details": {
        "mac": {
            "address": "8a:01:58:9c:48:fe"
        }
    },
    "created": 1766307723
},
{
    "id": 21233,
    "key": "device_discovery|8a:01:58:9c:48:fe",
    "event": {
        "id": 2,
        "tag": "device_discovery",
        "label": "Device Discovery"
    },
    "score": 0,
    "type": "update",
    "title": "Device identification update",
    "description": "An existing device (Unknown) has been re identified as iPhone",
    "details": {
        "mac": {
            "address": "8a:01:58:9c:48:fe",
            "discovery_hardware": "iPhone"
        }
    },
    "created": 1766310424
},

Events Subcription API

List All GET https://informatics.netify.ai/api/v1/events/subscriptions
List All for Identifier GET https://informatics.netify.ai/api/v1/events/subscriptions/{identifier}
List Record GET https://informatics.netify.ai/api/v1/events/subscriptions/{identifier}/{event_tag}
Create POST https://informatics.netify.ai/api/v1/events/subscriptions
Delete DELETE https://informatics.netify.ai/api/v1/events/subscriptions/{identifier}/{event_tag}

Please note: the subscription key is not returned in the subscription listings. 

# Example curl request to create a subscription
curl \
  -H 'x-api-key: {vendor_api_key}' \
  -H 'Content-Type: application/json' \
  -d '{ "identifier": "{uuid}", "driver": "netify.zenduty", "url": "https://abc.example.com", "key": "12345", "event_tag": "tor_detection", "score": 50 }' \
  -X POST 'https://informatics.netify.ai/api/v1/events/subscriptions'

Informatics Docs

Integration and Custom Solutions

Do you have any questions about integration, APIs or custom development?

Contact Us