Endpoint

Our system can create notifications and deliver them directly to your endpoint.
For example, when a sample file is generated for a campaign in your organization, we send real-time notification about the new file, which can be pushed to your endpoint.

Creating an Endpoint

You can only create one endpoint towards your organization.
Editing the already set endpoint can take up to 60 minutes to complete.
During this time both endpoints receive data.

Frontend:
1. Click "Connect your Endpoint with CarNEO"-Button.
2. Select endpoint type. We currently support these endpoint types: - Google PubSub Topic (recommend) - HTTPs Endpoint 3. Provide the url or topic you want your notification been sent to. - Google PubSub Topic: topic identifier as the uri, for example "projects/your-gcp-project/topics/your-topic-name".
- HTTPs Endpoint: HTTPs url as the uri, for example "https://example.com/notification-endpoint".

API:

PUT /endpoints/{organization_id}

{
  "type": "https",
  "uri": "string",
  "message_format": "protobuf"
}

or

POST /endpoints_v2/{organization_id}

{
  "type": "HTTPS",
  "message_format": "PROTOBUF",
  "uri": "string",
  "message_types": [
    "CONSENT_CREATION"
  ],
  "projects": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

The messages CarNEO push are encoded as Protobuffers by default.
The message format is configurable.

for endpoints:

"message_format": "json"

for endpoints_v2:

"message_format": "JSON",

Configure your Endpoint

Google PubSub Topic

Assign the "pubsub.topics.publish" permission or "roles/pubsub.publisher" role to CarNEO's gcp user.
CarNEO's static gcp user can be obtained from:

GET /endpoints/:configurationMeta

HTTPs Endpoints

Your endpoint have to reply to Ping Messages with a PingReply message in the response body.
All other messages don't require a specific response body.
Return a 2xx response code. Otherwise, the message delivery will be retried.
CarNEO posts data against the specified uri, hence verify the authenticity of incoming requests.
CarNEO's requests contain an "X-VWD-Signature" header. The signature is an JWT token that contains two claims: "algorithm" and "checksum". We currently use sha256 as an algorithm. You can verify the signature by using our public keys that are available through the GET /pki/public_keys endpoint.

Messages

The PROTOBUF and JSON message are structured identically.
Our systems send a "MessageContainer" object.
A MessageContainer contains multiple Message objects.

Each Message contains one of the following objects:

Ping
- We continuously send a Ping to your endpoint to validate if it is still working properly.
- If you are using an HTTPS endpoint, you must generate a MessageContainer that contains a Message with a PingReply object.
- The PingReply object must include your organization_id, and the is_valid_endpoint flag must be set to true.

PingReply
- Only required for HTTPS endpoints.

SampleNotification
- Sent when a new sample is created for one of your campaigns.
- Does not include actual vehicle data.
- Acts as a reference that can be used with the REST API (see "Accessing Samples").

StreamingData
- Sent if a campaign is configured to enable streaming.
- Contains the actual data from the vehicle.
- Can be used without utilizing the REST API.

ConsentRevocation
- Sent when a consent assigned to a project is removed.
- Includes the globally unique consent_id.
- All data you receive is tagged with the relevant consent_ids.
- Can be used to remove stored data on your infrastructure by matching the consent_id.