Step-by-step Guide

Step 1: Create a new TypeScript project

Create a new directory for your project and run the following command to initialize a new TypeScript project and add the required dependencies:

npm init -y
npm install --save express @adaptive-recognition/vehicle-detector-agent-webhook-middleware
npm install --save-dev typescript @types/express
npx tsc --init

This will create a new package.json file and install the required dependencies. It will also create a tsconfig.json file that contains the default TypeScript configuration.

The following table lists the dependencies that we have installed:

Package	Description
express	A Node.js web framework
@adaptive-recognition/vehicle-detector-agent-webhook-middleware	Middleware for parsing and verifying Vehicle Detector Agent webhook requests
typescript	TypeScript compiler
@types/express	TypeScript type definitions for Express

Step 2: Create a new Express app

Create a new file named app.ts in the root directory of your project and add the following code:

import express, { Express, Request, Response } from 'express';

const app: Express = express();
const port = 8080;

app.get('/', (req: Request, res: Response) => {
  res.send('OK');
});

app.listen(port, () => {
  console.log(`⚡️[server]: Server is running at https://localhost:${port}`);
});

This code creates a new Express app and listens on port 8080. The / route just returns OK to any GET request.

Step 3: Compile and run your app

Compile your TypeScript code by running the following command in your terminal:

npx tsc

This will compile your TypeScript code into JavaScript and create an app.js file in your project's root directory.

To start your server, run the following command:

node dist/app.js

This will start your Express app and you should see the following message in your console:

⚡️[server]: Server is running at https://localhost:8080

From a different terminal, you can now send a GET request to your server:

curl http://localhost:8080

You should see OK in the response.

Step 4: Choose a request signing algorithm

When it comes to digitally signing requests, there are two main types of signature algorithms: symmetric and asymmetric. Both types have their own advantages and disadvantages.

The algorithms supported by the Vehicle Detector Agent are:

Algorithm	Type	Description
HS256	Symmetric	HMAC using SHA-256 hash algorithm
HS384	Symmetric	HMAC using SHA-384 hash algorithm
HS512	Symmetric	HMAC using SHA-512 hash algorithm
RS256	Asymmetric	RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm
RS384	Asymmetric	RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm
RS512	Asymmetric	RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm
PS256	Asymmetric	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384	Asymmetric	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512	Asymmetric	RSASSA-PSS using SHA-512 and MGF1 with SHA-512
ES256	Asymmetric	ECDSA using P-256 and SHA-256
ES384	Asymmetric	ECDSA using P-384 and SHA-384
ES512	Asymmetric	ECDSA using P-521 and SHA-512

For this tutorial, we will use the RS256 algorithm. This algorithm is asymmetric, which means that it uses a public/private key pair to sign and verify requests. The public key is used to verify the signature, while the private key is used to sign requests.

To learn more about the different types of signature algorithms, check out our guide: Choosing a signature algorithm.

Step 5: Add the @adaptive-recognition/vehicle-detector-agent-webhook-middleware to your app

Add the following code to app.ts after the app declaration:

import { WebhookEvent, webhookSignatureValidator } from "@adaptive-recognition/vehicle-detector-agent-webhook-middleware";

const signatureValidator = webhookSignatureValidator({
  algorithm: "RS256",
  publicKeyPath: "/path/to/RS256.public.pem"
});

app.post('/webhook', signatureValidator, (req: Request, res: Response) => {
  const event: WebhookEvent = req.body; // req.body contains the parsed event
  console.log("Detected At: ", event.detectedAt);
  console.log("Unicode Text:", event.event.plate.unicodeText);
  res.send('OK');
});

This code imports the WebhookEvent type and webhookSignatureValidator function from the @adaptive-recognition/vehicle-detector-agent-webhook-middleware package, and adds a new route to our Express app at /webhook. The signatureValidator middleware is used to validate the request signature before the route handler is executed. The route handler logs some information from the parsed WebhookEvent object to the console and returns OK.

Step 5: Test your webhook server

Compile and run the server again:

npx tsc && node dist/app.js

The server now accepts POST requests at /webhook. To test the server, set the API_WEBHOOK_URL of the Vehicle Detector Agent to the URL of your webhook endpoint. If the encryption algorithm and public key are correct, you should see the requests logged to the console.