Receiving signals

Introduction

You have to subscribe to a webhook event to receive signals updates from a vehicle.

Updates will be sent at the endpoint provided at subscription time.

📘

Info

If you don't remember what a signal is, visit the Signals guide's page.

To subscribe to the events the request will consist of the following:

Body parameters table:

e.g.

{
    "hub.mode":"subscribe",
    "hub.topic":"vehicle:'UUID':generic:position",
    "hub.callback":"https//:example.com",
    "hub.secret":"A secret of your choice"
}

🚧

Warning

The parameter (hub.mode) is the actual properties name and not a body point notation.

📘

Info

To better understand this protocol visit this link.

To subscribe, your endpoint must be able to respond to a challenge performed at subscription time.

Challenge

The endpoint provided at subscription time will be called to check the URL validity.

The request will consist of the following:

You'll substitute https://example.com with your URL.

Headers table:

Query parameters table:

Example with the subscription URL being https://example.com:

https://example.com?hub.mode=subscribe&hub.topic=vehicle:'UUID':generic:position&hub.challenge=thisIsARandomString

Example of your system response:

thisIsARandomString

Topic

To receive signals updates you have to subscribe to a channel.

The topic is the channel identifier.

Special characters, such as wildchar * , can be used to target more than one element.

The structure is the following:

vehicle:$vehicleId:$signalType:$signalName

e.g. Using vehicle id 26c1097a-45d7-4719-a195-595c252a16f7 and signal position

vehicle:26c1097a-45d7-4719-a195-595c252a16f7:generic:position

You have to subscribe to specific signals individually.

Webhook

You receive signals at the endpoint provided at subscription time.

The call will consist of the following:

You'll substitute https://example.com with your URL.

Headers table:

Body table:

User's system has to answer within a predefined timeout (10 seconds), and it has to return Status OK (HTTP 200).

In case of error, we'll try again two times.

If the user's system fails to answer several times, we'll stop sending messages for a predefined amount of time.

This happens until the user's system can successfully receive messages. After that, the system resumes normal behaviour.

Messages signature calculation

Message's X-Hub-Signature is generated as follows:

import * as crypto from "crypto";

const generateSignature = (message: string, secret: string, algorithm: string): string => {
    if (!secret) {
      return "";
    }
    const hmac = crypto.createHmac(algorithm, secret);
    hmac.update(message, "utf8");
    return `${algorithm}=${hmac.digest("hex")}`;
}

const signature = generateSignature(body, secret, "sha256");

import hashlib
import hmac

def generate_signature(body: str, secret: str, algorithm) -> str:

    if secret is None:
        return ""

    h = hmac.new(secret.encode('utf-8'), body.encode('utf-8'), algorithm)

    return "sha256=" + h.hexdigest()

signature = generate_signature(body, secret, hashlib.sha256)

It uses the HMAC-SHA256 algorithm to create the signature from the JSON body.

The key is the one provided at subscription time.

📘

Info

If you want to test the contents of this guide, please refer to our testing environment.