Webhooks
The webhooks section allows you to create, configure, edit, secure and delete webhooks as triggers for events.
Webhooks are a non-standardized and very convenient way to trigger events in helmut.cloud. Technically, a webhook in helmut.cloud can be invoked with a standard HTTP POST request to its URL. To ensure the call to the webhook is authorized, configure the HMAC signing and validation with a pre-shared key. Additionally or alternatively, multiple HTTP-headers can be set, e.g. to define the payload. A payload limited to 4 MB can be attached to the call.
Event webhooks
With an event webhook, a single event out of many in a space can be triggered.
Click "+ Create webhook"
Choose "Event webhook"
Click "Go"
Choose a name
Connect an event from the drop-down list
Define a target account to execute the events stream
Below advanced options, you will find
Headers to e.g. define content-type, requests or responses
HMAC authorization headers
An encryption algorithm to use with HMAC
And the preshared key to use with HMAC
Space webhooks
A space webhook offers the option to call an event inside a space defined by the payload of the call.
Click "+ Create webhook"
Choose "Space webhook"
Click "Go"
Choose a name
Define the path to the exact event-name string in the calls payload (e.g. "status.event.name" for a JSON payload)
Define a target account to execute the events stream
Below advanced options, you will find
Headers to e.g. define content-type, requests or responses
HMAC authorization headers
An encryption algorithm to use with HMAC
And the preshared key to use with HMAC
Advanced Options
When creating or editing a webhook in High5, you can expand the Advanced options section to configure additional security, validation, and response behavior.
These options allow you to control how incoming webhook requests are validated and processed.
Webhook Callback
The Webhook Callback option allows you to send a custom HTTP response.
When enabled:
You can define a specific HTTP status code.
You can define a custom response body.
The default immediate response behavior is replaced.
This is useful when integrating with third-party services that expect a specific response format.
HTTP Headers Validation
You can require specific HTTP headers to be present in incoming webhook requests.
For each header, you must define:
Key – The header name
Value – The expected header value
The webhook request will not be processed if:
The required header is missing
The header value does not match
This adds an additional validation layer for incoming requests.
HMAC Validation
HMAC validation ensures that incoming requests are authentic and have not been tampered with.
HMAC Header Name
Specify the name of the HTTP header that contains the HMAC signature.
Example:
HMAC Algorithm
Select the algorithm used to generate the HMAC signature.
Example:
sha256
The selected algorithm must match the configuration of the external system sending the webhook.
HMAC Pre-shared Key
Enter the secret key used to generate the HMAC signature.
You can:
Enter your own secret
Generate one using the Generate option
The webhook request will only be processed if the signature matches the generated HMAC using this key.
IP Restrictions
You can restrict which IP addresses are allowed or denied from triggering the webhook.
IP addresses must be entered in CIDR notation.
Example:
IP Blacklist
Requests from IP addresses listed here will be rejected.
IP Whitelist
Only requests from IP addresses listed here will be accepted.
If both are configured, whitelist rules typically take priority depending on system configuration.
Security Recommendation
For production environments, it is recommended to:
Enable HMAC validation
Use a strong pre-shared key
Configure an IP whitelist
Validate required HTTP headers
This ensures that only authorized systems can trigger the webhook.
Webhook payload types and sizes
The calls payload can be very versatile, as helmut.cloud accepts many payload types. Yet we encourage our users to use JSON payloads that include the name of the source event.
All payloads are capped at 4 MB. As a consequence, helmut.cloud will discard all payloads larger than this.
Securing your webhook with HMAC signatures and validation
To secure communication between third-party applications and helmut.cloud against man-in-the-middle and replay attacks, it is recommended that the third-party posting to the webhook signs all payloads with an HMAC pre-shared key. helmut.cloud can provide a unique key during webhook creation or it can be included by the third-party in the response body.
During webhook creation, see the advanced options to configure HMAC authorization. You can set a header name, decide between SHA1 and SHA256 encryption and generate a PSK for your third-party application. This pre-shared key must remain secret at all times to ensure its function.
When HMAC validation is enabled, unsigned calls or calls with a wrong signature with be discarded.
Securing your webhook with custom headers
In case the posting third-party app does not support HMAC, it is possible to use custom headers to generate some layer of authentication. However, this is not as secure as signing with HMAC. Custom headers with a static secret may not help you evading MIM or replay attacks per default.
Webhook URL validation
In case a third-party application requires initial validation of the target webhook URL, it should first send a GET request with a query string called challenge. helmut.cloud will then respond with an HTTP 200 status code, echoing the value of the challenge query string in the response body.
The following HTTP headers will also be included:
Content-Type: text/plain
X-Content-Type-Options: nosniff
Webhook response codes
Once a webhook is triggered by the third-party application, helmut.cloud will respond to the POST request with the following HTTP status codes:
204with an empty body in case of success.400in case of a bad request.
Last updated