Powering Leon API with the webhook technology

Being perfectly suitable for applications developed with an advanced business model in mind, every GraphQL API may consist of 3 available types of operations:

• Queries - used to request the data from the system.
• Mutations - used to modify the data, or to execute other side effects.
• Subscriptions - allowing to push the data to external systems when particular events occur in the system.

Especially the third type of operations is worth exploring in more detail. Subscriptions provide API users with certain advantages, including a possibility to precisely define the scope of data received by the client. All the available subscriptions and returned data are incorporated in the API schema, which allows the user to use them in an almost similar manner to queries and mutations. GraphQL can be also used via Websocket or any other form of transport layer, whereas REST API depends only on HTTP.

A possibility to inform external services about events happening in the system is crucial when creating any kind of advanced integration between applications.

Our API has been implementing subscriptions for quite some time, yet from the point of view of third-party software suppliers they were not easily usable. This was resulting from utilising Websockets as a transport layer, which work fine in a server to browser communication, but create a number of issues while implementing a server to server communication. In order to provide our integrators with this new type of connection, we have decided to develop another type of transport layer for our subscriptions. And so, Webhooks have been introduced.

What are Webhooks?

Webhooks are often used in Web Development to notify external systems about particular events happening. It works in a manner that a target application should provide a source application with an URL address, to which notifications should be sent. In case of a particular event happening in the source system, a HTTP request is sent to a specific URL address and this way a target system receives information about an event.

How does it work in Leon?

A documentation for this part of our API can be found at Subscriptions via Webhooks website. In a nutshell, it works as follows:

1. An API user registers a webhook with a given URL address. It is done using a particular mutation.
2. During the registration process, a subscription query is provided, specifying events that will trigger the webhook. A list of available subscriptions can be found at the website http://api-schema-doc.s3-website-eu-west-1.amazonaws.com/subscription.doc.html
3. When a selected event happens, Leon will send related information to a registered URL address.

How can a subscription be used?

Subscriptions can be employed in a development of advanced integrations, especially when an instant data synchronisation is required. Among others, we already have implemented subscriptions that allow to react to following events in Leon:

1. Creating and modifying RFQ and a quote.
2. Changing the RFQ status.
3. Receiving a new message in the existing quote.

The list of supported events will be extended on the request of our community and according to our internal guidelines.

Not yet a member of Leon community? Contact our Sales team to find out more or jump straight into the 30-day free trial.