Skip to content

Webhooks

Webhooks allow you to create a custom endpoint for Alumio to receive data from external systems. There are many use-cases for this:

  • You want to receive data from an external system, but that system does not have an API.
  • The data is time-sensitive, and you want to receive it as soon as possible after a change (or create) happens.
  • You want to receive data from an external system, but you don't want to poll the API every X minutes to check for changes.

Generally, 'pull' strategies allow you some more control over the data you receive, but 'push' strategies have the advantage of being quicker.

When you've got high volumes and performance is a real issue, you shouldn't use webhooks. After all: if you poll a system every 5 minutes, you can batch all updates over those 5 minutes. If you receive a webhook, you'll have to process it immediately - meaning a single update has quite a bit of overhead.

How do Webhooks work?

When you create a Webhook, Alumio automatically creates a URL for you. This URL is unique.

In theory, Alumio accepts every request to this URL. However, you can add a 'matcher' to the Webhook to only accept requests that match certain criteria. For example, you can add a matcher to only accept requests that have a certain header, or a certain body.

When Alumio receives a request, it will check if it matches the criteria. If it does, it will send the data through to an Incoming configuration for you. The Incoming will receive the data from the Webhook like any other Incoming would, and you can process it further. This includes decoding the received data into JSON.

Settings

The following settings are important:

  • Incoming Configuration: Here you set one or multiple Incoming Configurations which will receive the data from the Webhook.
  • Enable Logging: Very important, don't forget to set this one! The Incoming will not log the data, so you can only log (and see) the data on the Webhook.
  • Processors: These allow you to set different types of matchers to only accept certain requests. For example, you can set a matcher to only accept requests with a certain header, or a certain body. Generally, a header with an 'Authorization' key is used to validate the request.
  • Response: If the other system requires a response, you can set it here. Generally, this is a simple 'OK' response.

About Security

Securing webhooks is a difficult topic. The webhook URL is so obscure, that it has a 'built-in' level of security.

However, this is NOT secure enough. Although many webhooks aren't really 'risky' ("updating a stock level" is not likely to be prime target for hackers), you should always be more secure than you think you need to be.

The best way to secure a webhook is to add a 'secret' to the webhook. This secret is a string that is known by both Alumio and the other system. The other system should add this secret to the request, and Alumio will check if the secret matches.