Webhooks listener setup

Introduction

We are providing you with a simple method to avoid the design of a webhook server to receive signals generated by vehicles in this system.

We want to help you create a server that, after subscribing to a webhook event, automatically responds to our challenge and receives the signals.


What you need to know

📘

Info

This tutorial makes you use the notions explained in the Receiving signals guide's page.
If you don't remember what a signal is, visit the Signals guide's page.

🚧

Warning

This guide is tested on Linux, specifically on Ubuntu 18.04LTS and Ubuntu 20.04LTS.


What you need to proceed

Follow the TypeScript guide

You need to install on your local environment some basic tools:

  • git,
  • node,
  • ngrok.

If you don't have one of these tools installed yet, we provide you with the steps to install them.

Otherwise, you can go to the How it works section.

Please open your terminal or press Ctrl+Alt+T.


Node installation

This project runs on node. Please, download node and install it.

Npm, a package manager for the JavaScript programming language, is needed to manage its dependencies.

Npm is included in node.


Git installation

Git is a distributed version control system for tracking changes in any set of files.

$ sudo apt install git

# check successful installation

$ git --version


You can directly download the repository for this tutorial as a .zip file and unzip it if you do not want to install git.


Ngrok installation

Ngrok is a tool that allows you to expose a local webserver.

To install it, you can click and follow the first two instructions from the guide provided on this link.


Using Python? Click me!

You need to install on your local environment some basic tools:

  • git,
  • python3.6,
  • pipenv,
  • ngrok.

If you don't have one of these tools installed yet, we provide you with the steps to install them.

Otherwise, you can go to the How it works section.

Please open your terminal or press Ctrl+Alt+T.


Python installation

We use python to develop this application. To be able to use it you have to install python3.6.

$ sudo apt-get install python3.6

# check successful installation

$ python3 --version


Pipenv installation

We use pipenv to create a virtual environment with all the application's requirements, so you won't have to install them on your local.

$ pip3 install pipenv

# check successful installation

$ pipenv --version


🚧

Warning

If you receive the following message while checking the version:

pipenv: command not found

It means you are not installing it globally.

The following command may help you:

$ sudo -H pip3 install -U pipenv

Git installation

Git is a distributed version control system for tracking changes in any set of files.

$ sudo apt-get install git

# check successful installation

$ git --version


You can directly download the repository for this tutorial as a .zip file and unzip it if you do not want to install git.


Ngrok installation

Ngrok is a tool that allows you to expose a local webserver.

To install it, you can click and follow the first two instructions from the guide provided on this link.



How it works


Download

Follow the TypeScript guide

First, you have to access the repository.

You can:

  • clone it via git,

$ git clone https://github.com/2hire/webhooks-listener-demo-ts.git


  • download it manually.

Download the .zip file at this link and then unzip it.


Using Python? Click me!

First, you have to access the repository.

You can:

  • clone it via git,

$ git clone https://github.com/2hire/webhooks-listener-demo-py.git


  • download it manually.

Download the .zip file at this link and then unzip it.




Set up

Follow the TypeScript guide

Now that you have the repository in local, you can go to the root of the project:

$ cd webhooks-listener-demo-ts


To create the server you have to install the web framework fastify.
To perform requests validation we are using JSON schemas.
To declare JSON schemas in your project you need to install the json-schema-to-typescript module.
It transforms JSON schemas into Typescript interfaces.

$ npm install


Now you can run the script to build the interfaces:

$ npm run compile-schemas


Using Python? Click me!

Now that you have the repository in local, you can go to the root of the project:

$ cd webhooks-listener-demo-py


Then you have to create an environment and download the dependencies based on the pipfile:

$ pipenv install --dev


🚧

Warning

If you receive a message like:

Warning: Python was not found on your system…

You can specify the specific version of Python that you are using with:

$ pipenv --python path/to/python

The following command may help you:

$ pipenv --python /usr/bin/python3 install --dev

Open a shell in the virtual environment that you just created.

The next time, on the same system, this is the only command you need to run:

$ pipenv shell


You should now see webhooks-listener-demo-py before your username.

To exit the virtual environment just type:

$ exit


Some useful CLI commands of pipenv:

# check dependency graph

$ pipenv graph

# check for known vulnerabilities

$ pipenv check




Run

Follow the TypeScript guide

To start the server you need to launch the typescript microservice and ngrok.


The typescript microservice

Once you have followed each step of the Set up section, you just need to compile:

$ npm run build


And run the code:

$ npm run start


You can add the hub.secret parameter when launching the application:

$ export SECRET=”My secret” npm run start


📘

Info

If you don't remember what the hub.secret is, visit the Receiving signals guide's page.


Ngrok

To start an HTTP tunnel forwarding to your local port 8080, open a new terminal, go to the same folder where you have downloaded ngrok and run this:

$ ./ngrok http 8080


The output will list the forwarding URL, which will point to your local server.

Session Status

Account

Version

Region

Web Interface

Forwarding

Forwarding

Connections

Online

[email protected] (Plan: Free)

2.3.35

United States (us)

http://127.0.0.1:4040

http://4caf6a3619e9.ngrok.io -> http://localhost:8080

https://4caf6a3619e9.ngrok.io -> http://localhost:8080

ttl  opn  rt1  rt5  p50  p90  

0   0   0.00  0.00  0.00   0.00


Copy-paste the link generated https://4caf6a3619e9.ngrok.io and add the suffix endpoint where the application will be called /listener.

Now you have your 'hub.callback': https://4caf6a3619e9.ngrok.io/listener.


Using Python? Click me!

To start the server you need to launch the application and ngrok.


The application

Once you have followed each step of the Set up section, and you are inside the virtual environment, you can launch the waitress dependence pointing at your application:

# Waitress - Application server

$ waitress-serve --call wld:create_app


You can add the hub.secret parameter when launching the application:

$ SECRET='My secret' waitress-serve --call wld:create_app


📘

Info

If you don't remember what the hub.secret is, visit the Receiving signals guide's page.

If you launch the application without the secret parameter, note that the default hub.secret is the same as in the tutorial: 'A secret of your choice'.


Ngrok

To start an HTTP tunnel forwarding to your local port 8080, open a new terminal, go to the same folder where you have downloaded ngrok and run this:

$ ./ngrok http 8080


The output will list the forwarding URL, which will point to your local server.

Session Status

Account

Version

Region

Web Interface

Forwarding

Forwarding

Connections

Online

[email protected] (Plan: Free)

2.3.35

United States (us)

http://127.0.0.1:4040

http://4caf6a3619e9.ngrok.io -> http://localhost:8080

https://4caf6a3619e9.ngrok.io -> http://localhost:8080

ttl  opn  rt1  rt5  p50  p90  

0   0   0.00  0.00  0.00   0.00


Copy-paste the link generated https://4caf6a3619e9.ngrok.io and add the suffix endpoint where the application will be called /listener.

Now you have your 'hub.callback': https://4caf6a3619e9.ngrok.io/listener.




Conclusions

Follow the TypeScript guide

Once you have launched the webhook-listener-demo-ts and ngrok you can finally subscribe to the signal of your interest.

Remember to pass the ngrok URL to the `'hub.callback' property.

{
    "hub.mode":"subscribe",
    "hub.topic":"vehicle:'UUID':generic:position",
    "hub.callback":"http://4caf6a3619e9.ngrok.io/listener", 
    "hub.secret":"A secret of your choice"
}

Using Python? Click me!

Once you have launched the webhook-listener-demo-py and ngrok you can finally subscribe to the signal of your interest.

Remember to pass the ngrok URL to the `'hub.callback' property.

{
    "hub.mode":"subscribe",
    "hub.topic":"vehicle:'UUID':generic:position",
    "hub.callback":"http://4caf6a3619e9.ngrok.io/listener", 
    "hub.secret":"A secret of your choice"
}


Did this page help you?