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.

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

Step 1 - Preparation

• Login to your account and receive an access token.
• Get our Base URL from the client setting API
• Using the Cameras API retrieve a list of the connected cameras to the end user.
• Pick the camera IDs that you want to check for events.

Step 2 - Creating an event subscription

By calling the following POST request you can create an event subscription:

curl --location '<base-URL>/api/v3.0/eventSubscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access token>' \
--data '{
  "deliveryConfig": {
    "type": "serverSentEvents.v1"
  },
  "filters": [
    {
      "actors": [
        "camera:<camera ID>"
      ],
      "types": [
        {
          "id": "een.motionDetectionEvent.v1"
        }
      ]
    },
    {
      "actors": [
        "camera:<camera ID>"
      ],
      "types": [
        {
          "id": "een.lprPlateReadEvent.v1"
        }
      ]
    }
  ]
}'

In the above request:

• deliveryConfig-type is serverSentEvents.v1.

📘

Note:

A single actor (camera) is supported in this version of the event subscription API. Multiple actors will be supported in the future.

• filters determine which events will be notified for each actor. This section allows you to specify what type of events should be notified (at the moment the supported actor is limited to camera). The different event types can be retrieved from the Events API.

📘

Note:

Currently the supported events for creating an event subscription filter are the following:

• een.motionDetectionEvent.v1
• een.lprPlateReadEvent.v1
• een.tamperDetectionEvent.v1
• een.loiterDetectionEvent.v1
• een.objectLineCrossEvent.v1
• een.objectIntrusionEvent.v1

More event subscriptions will be available in the future for other available events.

The response to the above request is the following:

{
    "id": "7ae45b1d-84c9-4b25-aba9-0f8db5fb43c7",
    "subscriptionConfig": {
        "lifeCycle": "temporary",
        "timeToLiveSeconds": 900
    },
    "deliveryConfig": {
        "type": "serverSentEvents.v1",
        "sseUrl": "https://api.c013.eagleeyenetworks.com/api/v3.0/sse/eventSubscriptions/7ae45b1d-84c9-4b25-aba9-0f8db5fb43c7"
    }
}

📘

Note:

The event subscriptions are temporary, and they are removed after 900 seconds if no client uses the sseUrl.

Step 3: Using the sseUrl

1. Call the following request with cURL:

curl --location "https://api.c013.eagleeyenetworks.com/api/v3.0/sse/eventSubscriptions/7ae45b1d-84c9-4b25-aba9-0f8db5fb43c7" ^
--header "Authorization: Bearer <access token>"

The above call will open a live session for receiving event data once it occurs. You will receive events as long as this session is open. The SSE URLs keep the URL valid and prevent it from expiring.

data:{"id":"100a77f3-2023-05-25T16:40:18.378Z-een.motionDetectionEvent.v1","startTimestamp":"2023-05-25T16:40:18.378+00:00","endTimestamp":null,"span":true,"isEndEstimated":false,"accountId":"00098540","actorId":"100a77f3","actorAccountId":"00098540","actorType":"camera","creatorId":"een.bridgeMotion","type":"een.motionDetectionEvent.v1","data":null}

The other endpoints of the /eventSubscriptions API allow you to GET valid event subscriptions, or delete them.