Trigger webhook

Registering a trigger webhook

A trigger webhook can be created using the menu item: "Triggers".

Add a new trigger and provide:

• Name: the name of the webhook (for administrative purposes only)

• Trigger type: choose "Webhook"

• Action: choices:

  • Execute ruleset

  • Start workflow

• Webhook slug: last part of the webhook endpoint

• Input name: When the webhook is called, the request data is gathered in one JSON object. This is the name of that JSON variable. The object contains the request headers, query parameters and the request body, an example output is shown on screen (see screenshot below).

• Log level: the level of logging to be used when the webhook is executed (none, all, warnings and errors, errors only)

• Ruleset name: the ruleset that will be executed (or the ruleset that will get its workflow started)

In the definition screen, the complete webhook URL is shown (see screenshot above) and will be something like:

https://{API_URL}/trigger/webhook/{TENANTNAME}/{WEBHOOKNAME}

Webhook security

Each webhook call is secured using the Rulecube API Key methodology. To be able to handle a webhook request, an API Key should be provided:

• via the Authorization header. Include the API Key in the request as follows:

  Authorization: YOUR_API_KEY

• or via a query parameter. Include the API Key in the query as follows:

  https://{API_URL}/trigger/webhook/{TENANTNAME}/{WEBHOOKNAME}?apiKey=YOUR_API_KEY

Ensure the API Key is always kept confidential and not exposed in publicly accessible locations. Always rotate your keys periodically to maintain security.

Since webhook calls are typically executed from a different domain, please ensure that the checkbox "Same Domain only" is unchecked in the API Key edit screen.

Webhook API Key permissions

If you use a webhook to execute a ruleset or to start a workflow, the API Key used should have enough permissions. For example, to execute a ruleset, the "RulesetExecute" permission should be enabled; however, to read or edit Persisted Entities, additional permissions must be enabled (Workspace_Read, Workspace_Edit).

Always ensure to assign just enough but not too many permissions!

• If not enough permissions are defined, your use case might fail due to insufficient permissions.

• If you define too many permissions, it can lead to unnecessary exposure and potential security vulnerabilities. Minimize permissions to reduce risks.