Event REST API

Overview

While the Javascript Library is the preferred mechanism for sending product usage data to Natero, there are some cases where it is inconvenient or infeasible. For example, if you have already instrumented your product to collect product usage internally, or if your product is not javascript-based (e.g., native apps, mobile apps).

The Event REST API is a way to send raw events directly to Natero. While using this API, considerations such as client-side caching, batching and compression must be implemented by the user of the API.

The API has a single end-point and operates entirely using HTTP POST requests.

NOTE: data sent via the event API is batch processed and is not immediately visible via the Natero UI. Data is aggregated every hour and is then viewable via the Natero Data Explorer. Data is then further aggregated every day and updates to some of the internal dashboards are only visible after the daily aggregation has occured.

General request URL

US Datacenter:
https://events.natero.com/v1/[yourAuthKey]/[yourApiKey]

OR

EU Datacenter:
https://events-eu.natero.com/v1/[yourAuthKey]/[yourApiKey]
If you are not sure of which datacenter to use please contact support@natero.com.

Terms

apiKey - A secret key by which a user's event stream is identified. With this key, anyone can upload events as the user to the matching source.

authKey - A second secret key used to authenticate user. You need both the authentication key and the api key to successfully upload an event to the Natero servers.

The authentication and api keys are tied together and are unique to a source, both are generated by the website when creating a direct to Natero source.

The api key and authentication keys are provided by Natero and can be requested by email support@natero.com.

Request format

An HTTPS POST on the request URL with the body containing a series of JSON objects defining individual events. Multiple events can be batched within a single POST request. Each event must be separated by and end-of-line marker, indicated either by '\r\n' or '\n'. Events MUST NOT be formatted as a JSON array.

The 'Content-Type' header should be set to 'application/json' and the 'Content-Length' header should also be set.

For example, this is the correct format, notice NO [], nor commas between events:

POST /v1/authkey/apikey  HTTP/1.1
HOST: events.natero.com
Content-Length: 593
Content-Type: application/json

{ "accountId": "id", "userId": "id", "createdAt": number, ... }
{ "accountId": "id", "userId": "id", "createdAt": number, ... }
{ "accountId": "id", "userId": "id", "createdAt": number, ... }

Compression

You may optionally compress JSON events in the request body using either GZip or Deflate.

If compressing with Gzip, the 'Content-Encoding' header must be set to 'gzip'.

If compressing with Deflate, the 'Content-Encoding' header must be set to 'deflate'.

Any other header values will be regarded as plain text json.

Responses

Responses contain no body, only an HTTP response code. The returned code is either 200 (OK) on success or 400 (BAD REQUEST) on failure. Failure is the result of either an invalid request type (e.g., not POST) or an invalid path (guid and/or source). Invalid events are silently dropped by the server.

Ping Interface

You can ping the server over https by sending a POST to https://events.natero.com/v1/ping

The server response will return a 200 OK code if the server is reachable and no message body.

JSON format

The JSON data for events *should* contain the following base properties. These base properties should be sent with every event:

{
  // Required
  accountId: string, (A unique account ID, required)
  userId: string, (A unique user ID, required)
  createdAt: number, (event's timestamp in epoch milliseconds, required)
  action: string (event string, see below, required)
  sessionId: string, (client session id; typically expires in 30 minutes, required),
}

Supported events

All supported events (actions) are described below along with their associated properties that make up the JSON data object.

The core events that should be implemented are for primary data tracking are:

Supporting events that are useful for adding new or updating existing accounts/users:

The full api follows:

Testing

To verify that your app has been properly instrumented, you can use the Natero Instrumentation Viewer. Use the endpoint of: https://test.natero.com/v1/[yourAuthKey]/[yourApiKey] when sending the events and follow the instructions on the Instrumentation Viewer page to view your events.

Example upload with CURL

You can easily use curl to upload events to either the Instrumentation Viewer (see above) or to the production event collector.
curl -X POST -T file.json https://events.natero.com/v1/<auth_key>/<api_key>

Alternate JSON formats

If your data does not fit with the JSON event format described above, we may still be able to work with your data. Please contact support@natero.com with a description of your data and you will be connected with one of our engineers who can help you with your integration.