Event Subscriptions

Introduction

The Eagle Eye Networks Video API v3 provides an /eventSubscriptions feature based on SSE (Server-Sent Events). SSE is a server push technology enabling a client to receive automatic updates from a server via an HTTP connection and describes how servers can initiate data transmission towards clients once an initial client connection has been established. In the Eagle Eye Video API v3, SSE is used to receive events of different types once they occur.

The Eagle Eye Networks Video API v3 enables real-time event notifications through event subscriptions. These subscriptions allow clients to receive alerts about various events as they occur.

Below are the steps to create an event subscription and define filters for it.

Selecting a Delivery Method

You can choose how events are delivered to your application. The API currently supports two delivery methods: Server-Sent Events (SSE) and Webhooks.

SSE (Server-Sent Events)

SSE is a server push technology enabling a client to receive automatic updates from a server via an HTTP connection and describes how servers can initiate data transmission towards clients once an initial client connection has been established. This method is ideal for real-time streaming of events.

Creating an SSE Subscription

To create an SSE subscriptions, you'll need to send a POST request to the /eventSubscriptions endpoint. The request should include a deliveryConfig object with the type set to serverSentEvents.v1.

curl --request POST \
     --url https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "deliveryConfig": {
    "type": "serverSentEvents.v1"
  },
  "filters": [
    {
      "actors": [
        "camera:100d4c41"
      ],
      "types": [
        {
          "id": "een.motionDetectionEvent.v1"
        }
      ]
    }
  ]
}
'

const url = 'https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions';
const options = {
  method: 'POST',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: JSON.stringify({
    deliveryConfig: {type: 'serverSentEvents.v1'},
    filters: [{actors: ['camera:100d4c41'],
    types: [{ id: 'een.motionDetectionEvent.v1' }]}],
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions"

payload = {
    "deliveryConfig": { "type": "serverSentEvents.v1" },
    "filters": [
      {
        "actors": ["camera:100d4c41"],
        "types": [{ "id": "een.motionDetectionEvent.v1" }]
      }
    ]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Once created, the API returns an SSE URL, which can be used to listen for events:

{
  "id": "f3d6f55d5ba546168758a309508f4419",
  "subscriptionConfig": {
    "lifeCycle": "temporary",
    "timeToLiveSeconds": 900
  },
  "deliveryConfig": {
    "type": "serverSentEvents.v1",
    "sseUrl": "https://api.c013.eagleeyenetworks.com/sse/v3.0/eventSubscriptions/f3d6f55d5ba546168758a309508f4419"
  }
}

Connecting to an SSE Subscription

Once a Server-Sent Event subscription has been established, you may begin listening for events by following the SSE url. You'll need to authenticate your connection by including a valid access token in the Authorization header.

curl --request POST \
     --url https://api.c013.eagleeyenetworks.com/sse/v3.0/eventSubscriptions/f3d6f55d5ba546168758a309508f4419 \
     --header 'Authorization: {access_token}'

🚧
SSE Subscriptions are Temporary
SSE subscriptions are not meant for long term use. If an event is not detected or the SSE is otherwise not used for 900 seconds, it will expire. For more a more durable solution, we recommend using the Webhook option.

Webhook Subscriptions

Webhooks allow events to be delivered via HTTP POST requests to a specified URL. This is useful for integrating with external systems.

Creating a Webhook Subscription

To create a webhook subscription, you'll need to send a POST request to the /eventSubscriptions endpoint. The request should include a deliveryConfig object with the type set to webhook.v1. This object must also include the webhookUrl where the webhook events are to be sent. You'll also need to include a technicalContactEmail and technicalContactName.

curl --request POST \
     --url https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "deliveryConfig": {
    "type": "webhook.v1",
    "webhookUrl": "https://example.com",
    "technicalContactEmail": "tech@example.com",
    "technicalContactName": "Tech Contact"
  },
  "filters": [
    {
      "actors": ["camera:100d4c41"],
      "types": [{ "id": "een.motionDetectionEvent.v1" }]
    }
  ]
}'

const url = 'https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions';
const options = {
  method: 'POST',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: JSON.stringify({
    deliveryConfig: {
      type: 'webhook.v1',
      webhookUrl: 'https://example.com',
      technicalContactEmail: 'tech@example.com',
      technicalContactName: 'Tech Contact'
    },
    filters: [
      {actors: ['camera:100d4c41'],
      types: [{ id: 'een.motionDetectionEvent.v1' }]}
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.cxxx.eagleeyenetworks.com/api/v3.0/eventSubscriptions"

payload = {
    "deliveryConfig": {
        "type": "webhook.v1",
        "webhookUrl": "https://example.com",
        "technicalContactEmail": "tech@example.com",
        "technicalContactName": "Tech Contact"
    },
    "filters": [
      {
        "actors": ["camera:100d4c41"], 
        "types": [{ "id": "een.motionDetectionEvent.v1" }]
      }
    ]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Applying Filters

When creating an event subscription, you can apply a filter determine which events trigger notifications and which devices are included in the subscription.

Filter by Actor

To filter by actor, you can specify the actors array in the filter object. The actors array should contain the type of actor and the actor ID. For example, to filter by camera, you would use camera:<camera ID>. At the moment, only a camera is supported as an actor.

"actors": [
  "camera:<camera ID>"
]

Filter by Event Type

To filter by event type, you can specify the types array in the filter object. Each item in the array should contain a id property with the event type ID. For example, to listen for motion detection and license plate read events, you would use the following filter:

"types": [
  {
    "id": "een.motionDetectionEvent.v1"
  },
  {
    "id": "een.lprPlateReadEvent.v1"
  }
]

📘
To get a list of available event types, you can use the /eventTypes endpoint.

Introduction

Selecting a Delivery Method

SSE (Server-Sent Events)

Creating an SSE Subscription

Connecting to an SSE Subscription

🚧SSE Subscriptions are Temporary

Webhook Subscriptions

Creating a Webhook Subscription

Applying Filters

Filter by Actor

Filter by Event Type

📘

🚧
SSE Subscriptions are Temporary