Introduction

A webhook is a standard in the world wide web. A webhook can be defined as an http request that is generated in response to a certain event. This standard is usually provided to third-party solutions to allow them to receive notifications or status updates of a particular entity of the application concerned.

Here is an example within Tilby: it is possible to receive notifications on events such as the creation, modification and closure of sales generated by the Tilby application.

How it works

It is possible to connect to multiple entities. By entity we mean the main models that can be used by the API. You can find details in the documentation  for the exceptions of the stock and daily_closing entities. You can find those models at the bottom of this document.

When a webhook is hooked to one of the available entities (see next paragraph for the complete list) it is necessary to provide:

• an URL HTTPS allowed to receives request with POST method;
• a STATIC TOKEN FROM TILBY generated by the shop you want to integrate here  you can find details on how to generate a static token);
• the ENTITY NAME you want to listen;
• the EVENT TYPE available with the entity set up before;
• a VALID EMAIL. This email will be used to notify you every request sent from the webhook system that got an error

After this, our system will send a request to the url every time that a notification matches the webhook details.

For example:

If you want to generate a webhook every time that a sale is closed, you should set up a webhook with these parameters:

• URL of your integration
• STATIC TOKEN of the shop
• "sales" as entity name
• "closed" as event type
• EMAIL of the developer that should be notified if a webhook request did not work.

The entity model depends on the entity name chosen and the event type chosen. You can find more information at the bottom of this documentation.

If the http request to your url fails, our system will try to send the message again at least 3 times, waiting for 15 minutes after each retry.  You'll be notified for each retry error by email with the body of the request. At the last retry you will be notified that that message reached the limit retry rate

Your system that receives the http request of the webhook must answer with  STATUS CODE equal to 200 otherwise we consider the request as failed starting the system retry.

How to set up a webhook

First of all you need a STATIC TOKEN generated from the shop you want to integrate. You will use this token as AUTHORIZATION HEADER in the http POST request used to create a webhook.

For each shop it's possible to have just 1 webhook for each combination of entity_name and event_type.

When you set up a webhook our backend will verify that the url you passed can answer a test request. The body of the http post request will be like this:

 {

                "type": "SUBSCRIBED",

                "entity_name": "{entity}",

                "time": "2022-02-23T15:43:31.714Z",

                "environment_id": "id_of_the_shop",

                "client_id": "clientId_of_static_token"

 }

In order to change a webhook you need to DELETE it and then insert it again with the new changes.

Importing exception

When an Importing is done, the webhook's messages are sent in batches. You will receive a maximum of 80 entities in a single batch for main entities: items and customers. Stock movements, fidelity movements and prepaid movements are not considered.