> For the complete documentation index, see [llms.txt](https://docs.rulecube.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rulecube.com/v2.5/how-to-guides/webhooks/trigger-webhook.md).

# 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)

<figure><img src="/files/KRuJCKzk4qvcRKagG42B" alt=""><figcaption></figcaption></figure>

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

```http
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:

  ```http
  Authorization: YOUR_API_KEY
  ```

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

  ```http
  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.

{% hint style="info" %}
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.&#x20;
{% endhint %}

### 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`).&#x20;

{% hint style="info" %}
Always ensure to assign just enough but not too many permissions!&#x20;

* 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.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rulecube.com/v2.5/how-to-guides/webhooks/trigger-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.