Setup a demo server to listen to webhooks events

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.

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.

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.

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.

🚧

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.

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.

First, you have to access the repository.

You can:

• clone it via git,

• download it manually.

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

First, you have to access the repository.

You can:

• clone it via git,

• download it manually.

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

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

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.

Now you can run the script to build the interfaces:

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

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

🚧

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:

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

To exit the virtual environment just type:

Some useful CLI commands of pipenv:

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:

And run the code:

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

📘

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:

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

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.

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:

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

📘

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:

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

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.

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"
}

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"
}