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.

The following diagram explains the process of subscribing, receiving events, and unsubscribing via the webhook endpoint.

Subscription

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 pattern visit this link.

There are multiple events you can subscribe to. Check the following section to understand how they are defined.

Topic

This section explains how the topic is defined.

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

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 challenge for vehicle:'UUID':generic:position topic.

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.

📘

Do you need some help?

To help you manage to receive signals from our system, we produced some tutorials and cookbooks to help you understand this topic.
Visit:

• Webhooks listener implementation
• Webhooks listener setup
• Message signature validation