Configuring Webhooks

This guide will show how to configure and use a webhook within Alumio. Webhooks allow third parties to send data to Alumio which in turn will be processed by a subscriber.

Configure a subscriber

Webhooks require a special webhook subscriber in order to be able process received data. A subscriber can be configured via the dashboard. Go to Connections > Incoming. Then click the add button on the top of the page.

Subscriber

Fill in the basic information like name, identifier, and description. Then select "Webhook" from the Subscriber drop down menu.

Parser

Select a Parser from the Parser drop down to configure the content type that the webhook will receive.

Binary
The binary parser can be used when receiving binary files. It requires no further configuration.

CSV
The CSV parser can be used when receiving data in CSV format. A delimiter, enclosure and escape character can be configured.

JSON
The JSON parser can be used when receiving data in JSON format. A JMESPath expression can be entered to specify a path to the relevant items.

XML
The XML parser can be used when receiving data in XML format. A JMESPath expression can be entered to specify a path to the relevant items.

Configure subscriber

Configure a webhook

After a subscriber is configured the webhook can be created. Navigate to the webhook section via Connections > Webhooks.

A table will show the configured webhooks. To configure a new webhook click the plus icon in the top right.

Webhooks overview

Fill in the basic information like name, identifier, and description. Then select the configured subscriber from the "Incoming Configuration Identifier" drop down. The configured subscriber will be used the process data sent to the web hook.

Webhooks form

Request processors

Request processors can be added to a webhook. One of the main reasons is to add a form of authentication to a webhook. This is done with the request validator, which can be configured to compare parts of the incoming request to the created settings. This allows the request to be compared to many aspects of an incoming request.

Click the "Add Pre processors" to add a processor. Then select "Request validator" drop the drop down menu.

Select "Header Matcher" in the "Matcher" drop down menu to configure a simple authentication. Enter "Authorization" as "Header Name" and "Bearer ExampleToken" as "Pattern".

Enter "403" in the "HTTP Status Code When No Match" field and enter a message that should be displayed when no match could be found.

When a request to the webhook is performed without the authorization header "Bearer ExampleToken" the data is not stored an the API will return a 403 error response. When no authentication is required the processors can be left out. Warning: This will allow anyone with knowledge of the webhook URL to post data to the webhook.

Configure Authentication

Posting data to a webhook

After a webhook is created it can be used to receive data. Data can be send to https://{environment}.alumio.com/api/v1/webhook/{identifier} via a POST request where {alumio-host} is the URL of Alumio and {identifier} the entered identifier of the webhook.

The URL can be copied to the clipboard by navigating to the webhook overview page and clicking the Copy to Clipboard button.