Table Of Contents
- Introduction
- Step 1: Create an incoming configuration
- Step 2: Create a webhook
- Step 2a: Setting the basics
- Step 3: Testing the webhook
Introduction
A Webhook enables a web service that makes it possible for other systems to send information in real-time to Alumio. Webhooks are commonly used to trigger logic in other systems when new data is retrieved or existing data is updated. Alumio allows you to create an API endpoint (webhook) for external systems to send data to.
One webhook may send information from one system to multiple other systems. An example of a webhook would be a Warehouse Management System (WMS) that ships an order. When this happens, the WMS sends an API request to Alumio. Alumio then takes the information sent by the WMS to perform two actions in two different systems:
- The order is completed in the ERP system.
- The tracking details are sent to the customer through the eCommerce system.
Before we continue it is important to understand how the architecture of webhooks has been set up. An end-to-end webhook integration within Alumio consists of the following components:
- Webhook configuration - The webhook configuration enables an API endpoint for another system to send data to Alumio.
- Incoming Configuration - The webhook configuration only accepts the incoming data but does not do anything with it. An incoming configuration is created to catch the data and make it available within an integration.
- Outgoing Configuration - The outgoing configuration determines to which system the data is sent.
- Route Configuration - The route configuration glues the incoming configuration and the outgoing configuration to each other, enabling the integration between two systems.
- (Optional) Entity Transformer Configurations - If needed, entity transformers can be used to transform the data to make it compatible with the receiving end.
The description given has been visualized in the figure above. Please note that the figure below shows an additional route configuration tied to the same webhook endpoint. thank you to Alumio’s modular architecture this is possible.
For this guide, we will set up a webhook that is configured to verify whether authorization is present and it is configured to accept XML data.
Step 1: Create an incoming configuration
First, choose the relevant subscriber prototype: Webhook
Now it’s time to fill in the required fields and set up the connection.
- Parser - Select the type of incoming data you are expecting to process. Alumio will use the parser to translate the data to JSON.
- (XML only) Read method - Depending on the system you may receive enormous files in a single API call. To improve the processing time you may opt to select the Incremental read method.
- Pattern to items - Within Alumio we suggest splitting multiple data entities into single ones. This option enables Alumio to automatically do this.
Step 2: Create a webhook
This section will explain how to set up a Webhook that can be used by other systems to send data to.
Step 2a: Setting the basics
To set up a webhook the generic webhook guide can be followed: Webhooks
Make sure to select the incoming configuration created in step 1 when setting up the webhook.
(Optional) Step 2b: Setting up authentication
The API endpoint exposed by the webhook is publicly accessible by anyone. In many cases, you want to ensure that only authorized parties are communicating data to Alumio. This can be used by setting up a Request Validator that will enable Alumio to perform configurable validations on incoming requests. Within this example, a request validator will be set up to see if the external system provides an X-Alumio-Auth header with the specific value of VerySecret.
Step 3: Testing the webhook
To test the webhook you may use another system or tool. For this guide, the API testing tool Insomnia (https://insomnia.rest/) is being used.
In order to test the webhook, it is needed to retrieve the API endpoint. The base URL for the webhooks API endpoints can be found under Settings → Info.
Now it’s time to send the API request to Alumio.
As you can see, we are being returned a 401 Unauthorized status code with the following error message: Wrong authentication token provided. Exactly as expected, because a request validator was set up to see whether the X-Alumio-Auth header is provided with the correct value. Let’s retry this request with this header being present.
Alumio now returns a 200 OK status code. This means the webhook has successfully been processed and any tasks are now available within Alumio.
