Subscription API

Use the Subscription API to subscribe and manage subscriptions to events from the Novo Cloud. The Request URIs with Request and Response structures are described below with some samples.

Use the Subscribe API to create new subscription. After a subscription is created, it has ACTIVE status but it needs to be confirmed by the receiving party to actually start receiving notifications.

For HTTP/S endpoint, There is no need of subscription confirmation. Notification Service Push API below is the description of a notification message sent to the endpoint as a HTTP POST request.
For email endpoint, simply check your inbox and follow the link in the confirmation email.

Request URI

Request URI	Method
/notification/v1/subscription	POST

Request body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
target_type	string	required	Notification channel (HTTP/HTTPS, EMAIL).
target_uri	string	required	Identifier of the receiving endpoint for the notification channel. For HTTP/HTTPS, it's a URL (both http and https are supported). For email, it's an email address.
events_definition	object	required	A filter to select which events to subscribe to.

Events Definition JSON object:

Name	Data Type	Required/Optional	Description
domains	array of strings	required	Event domains to subscribe to. At least one domain must be specified.
include_event_types	array of strings	optional	Event types to subscribe to. Empty/absent include_event_types field means "All event types included".
exclude_event_types	array of strings	optional	Event types to exclude from subscription. Applicable only when "include_event_types" is absent or empty. Empty/absent exclude_event_types field means "None of the event types are excluded". If same event type is listed both in include_event_types and exclude_event_types, it's excluded.
include_sources	array of strings	optional	Sources to subscribe to. Empty/absent include_sources field means "All sources included".
exclude_sources	array of strings	optional	Sources to exclude from subscription. Applicable only when "include_sources" is absent or empty. Empty/absent exclude_sources field means "None of the sources are excluded". If same source is listed both in include_sources and exclude_sources, it's excluded.

Definitions:

domain: Describes the domains of event with respect to the occurrence origin. The value for this field must be obtained from Novo for a given event / context and included when publishing events.
event_type: Describes the type of event with respect to the occurrence origin. Could be data update event, engine start/stop event, service job finish event etc. The origin would typically be a system or device such as a vehicle, data publishing server, etc.
source: Identifies the source context of an event. Could be a device id, an instance id or the host of a service

Info

The list of values for source, domain and corresponding event_type to use will provided at the time of integration.

Events Sampling JSON object:

Name	Data Type	Required/Optional	Description
events_definition	object	required	A filter to select events, which are subject to this sampling rule. If an event matches more than one filter, then the first matching sampling rule applies (from top to bottom, JSON array order).
properties	object	optional	Properties map for selected sampling_type.
sampling_type	string	required	Sampling type. Supported samplers in table below

Supported samplers:

Sampler	Description	Properties
EVENT_PER_PERIOD	Delivers at most 1 event per event type per period (per ordering_key)	period - integer, period length in seconds

Request example 1 JSON

{
  "target_type": "HTTP",
  "target_uri": "http://example.com/novo/notifications",
  "events_definition": {
    "domains": ["domain1", "domain2"],
    "include_event_types": ["eventType1", "eventType2"],
    "include_sources": ["source1", "source2"]
  }
}

Request example 2 JSON

{
  "target_type": "HTTPS",
  "target_uri": "https://example.com/novo/notifications",
  "events_definition": {
    "domains": ["domain1", "domain2"],
    "exclude_event_types": ["eventType3", "eventType4"],
    "exclude_sources": ["source3", "source4"]
  }
}

Request example with sampling JSON

{
  "target_type": "HTTPS",
  "target_uri": "https://example.com/novo/notifications",
  "events_definition": {
    "domains": ["domain1", "domain2"],
    "include_event_types": ["eventType1", "eventType2"],
    "include_sources": ["source1", "source2"]
  },
  "events_sampling": [
    {
      "events_definition": {
        "domains": ["domain1"],
        "include_event_types": ["eventType1"]
      },
      "sampling_type": "EVENT_PER_PERIOD",
      "properties": {
        "period": 5
      }
    },
    {
      "events_definition": {
        "domains": ["domain1"],
        "include_sources": ["source2"]
      },
      "sampling_type": "EVENT_PER_PERIOD",
      "properties": {
        "period": 60
      }
    }
  ]
}

Response body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	object	required	Status (see above in Common section)
subscription_id	UUID	required for successful response	Id of a newly created subscription

Sample response JSON

{
  "status": {
    "code": 26200,
    "message": "Success"
  },
  "subscription_id": "043f56f4-aec6-11eb-8529-0242ac130003"
}

Get Subscription

Use the Get Subscription API to get existing subscription details.

Request URI

Request URI	Method
/notification/v1/subscription/{id}	GET

Request parameters

Name	Description
id	Id of the subscription as returned by Subscribe endpoint.

Response body

Same as response body of Subscribe endpoint.

Get All Subscriptions

Use the Get All Subscriptions API to get a list of subscriptions belonging to the current user.

Request URI

Request URI	Method
/notification/v1/subscriptions	GET

With Pagination support:

Request URI	Method
/notification/v1/subscriptions?page-number={page-number}&page-size={page-size}	GET

Request parameters (optional)

Name	Description
offset	Start index
limit	The number of data elements to be returned in the response

If any parameter is invalid (null or <1), then both are ignored, entire list is returned.

Response body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
offset	long	required	Start index of the list.
data	object	required	Complex structure, containing an array of elements of subscription id and subscription itself.

Sample response JSON

{
  "page": 1,
  "data": [
    {
      "id": "bba7126a-f4ff-40a4-995c-6c9c01eb688c",
      "subscription": {
        "target_uri": "https://example.com/novo/notifications",
        "events_definition": {
          "domains": [
            "domain1"
          ],
          "include_event_types": [
            "eventType2"
          ]
        }
      }
    },
    {
      "id": "eb93684b-61af-4fed-a1bf-ac5c302d48ad",
      "subscription": {
        "target_uri": "https://example.com/novo/notifications",
        "events_definition": {
          "domains": [
            "domain1"
          ],
          "include_event_types": [
            "eventType1"
          ]
        }
      }
    }
  ]
}

Unsubscribe

Use the Unsubscribe API to cancel an existing subscription. After cancellation, the subscription won't be available through the API anymore.

Request URI

Request URI	Method
/notification/v1/subscription/{id}	DELETE

Request parameters

Name	Description
id	Id of the subscription as returned by Subscribe endpoint.

Response body

Common status response. See common status response.

Get Subscription Status

Use the Get Subscription Status API to get the current subscription status.

Request URI

Request URI	Method
/notification/v1/subscription/{id}/status	GET

Request parameters

Name	Description
id	Id of the subscription as returned by Subscribe endpoint.

Response body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	string	required	Current status of the subscription (ACTIVE, PAUSED)
last_change_reason	string	required	Reason for the last status change. For example, "Manual change" (when changed via API), "Paused due to too many endpoint errors", "Paused due to license expiration", etc. May be useful for customers for debug purposes.
last_change_time	string (RFC 3339)	required	Last status change time.

Sample response JSON

{
  "status": "ACTIVE",
  "last_change_reason": "Manual change"
  "last_change_time": "2020-03-24T00:08:46.940-0700"
}

Change Subscription Status

Use the Change Subscription Status API to activate or pause the subscription.

Request URI

Request URI	Method
/notification/v1/subscription/{id}/status	PUT

Request parameters

Name	Description
id	Id of the subscription as returned by Subscribe endpoint.

Request body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	string	required	Desired status of the subscription (ACTIVE, PAUSED)

Response body

Common status response. See common status response.

Push API

The following HTTP POST request is an example of a notification message sent to the http/https endpoint subscribed to the Notification Service.

Method : POST

Request headers These are headers common to all endpoints of the API.

Name	Description
x-tn-subscription_id	Novo assigned Subscription Id

Sample Headers

Content-Type: application/json
x-tn-subscription_id: 22b80b92-fdea-4c2c-8f9d-bdfb0c7bf324

Request body

Top-level JSON object:

Novo Event Object

Notes:

Make sure that your endpoint responds to the HTTP POST message from Amazon SNS with the appropriate status code
The connection will time out in 5 seconds. If your endpoint does not respond before the connection times out or if your endpoint returns a status code outside the range of 200–4xx, Notifictaion Service will consider the delivery of the message as a failed attempt.
Make sure that your code can handle message delivery retries. If Notiifctaion Service doesn't receive a successful response from your endpoint, it attempts to deliver the message again. By default, if the initial delivery of the message fails, it will attempts up to three retries with a delay between failed attempts set at 20 seconds.