> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Trigger automations with webhooks and use webhook data in custom tasks.

## Preface

This document introduces Qbilon's Webhook Triggers feature. It allows you to push arbitrary JSON data to Qbilon, which you can then use in your automations.

## Creating Webhook Triggers

The `Webhooks` section can be found under `Automations`. Initially, an empty list is shown. To create a first Webhook Trigger, simply click `Create Webhook +` and enter a custom name.

### Standard Triggers

Standard Triggers can be given a name and provide a unique URI that serves as the endpoint to which data can be sent. Whenever data is sent to this endpoint, all associated automations will be triggered immediately (see "Using Webhook Triggers" below). Once you have created a Standard Trigger, it will be displayed in the list.

![Webhooks: Standard Triggers](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/110b1f06-9126-4493-b71d-6def8f0f89fd-screenshot-2026-09-30-144937.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=76d22082bc1a6e0b5aef61952da11c4c)

A unique URL has been created for both trigger types, which you can see in the `URL` column. You can now send data to this URL. While you can change the name of your trigger later by clicking the `Edit` button (pencil icon), you cannot change the URL. The only thing you can change is the name under which your Webhook Trigger appears in Qbilon.

## Using Webhook Triggers

Webhook triggers are designed for use with automations. You can configure a webhook to initiate an automation. This means that whenever an authenticated request is sent to the webhook trigger, your automation will begin. You can then access the data sent via your [Custom Tasks](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/index) within the automation.

As explained above, to use a Webhook Trigger, start by creating or editing an automation in the `Automations` section.

For existing automations, just click on the "start node" (the circle node at the beginning of the topology visualization) and then on "Edit" in the right side panel. Select `Webhook` as `Trigger Type` and choose a webhook from the dropdown list.

![Webhooks: Using Webhook Triggers](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/a89b9692-00ac-4442-9842-86fbc54e9278-screenshot-2026-10-06-152851.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=22126a349ef5ded6c98c3fde3e4a8b30)

For newly created automations, the `Trigger Type` can be selected directly in the appearing dialogue.

![Webhooks: Using Webhook Triggers](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/928efc7f-40bb-41cb-9190-49f54f2a03ec-screenshot-2026-10-06-153516.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=b1ec28176ab0d85e3fd90c1e77b2e8bc)

Congratulations! You now have an automation that can be triggered outside of Qbilon by calling your configured Webhook Trigger.

## Calling Webhook Triggers

Now that you have successfully connected a Webhook Trigger to a automation, you can trigger it from outside of Qbilon. You just need three pieces of information to do so – the Webhook Trigger's URL, an API key to authenticate against this URL, and your tenant name.

* The **Webhook Trigger URL** is the easiest part as you can simply copy it from the Webhook Trigger you just created, e.g., `https://my-to.acme.com/webhooks/execute/fea815e2-0fd9-4978-8243-22330235c4a9`.
* The **API Key** can be retrieved from the `Settings` page in the section `API Key` and looks usually similar to something like `ciEyu3lm2BMndGqf1SOmnzLhoLMDMJSU`.
* The **Tenant Name** is simply the name visible in your Keycloak instance provided by Qbilon. As an administrator, go to "Settings → User Management → Manage Realm". Your "Tenant Name" is displayed in the top left corner.

![Webhooks: Calling Webhook Triggers](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/15be5562-7d2f-425f-9fe9-8bf21c04ee61-image.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=02f75b16084dacc84aff89a9e5b25e52)

Now that you have all the necessary information, you can send a simple HTTP POST request to the endpoint using the following format:
`<Webhook Trigger URL>?qbilon-api-key=<API Key>` .

Currently, we only accept valid JSON in the body of this POST request. However, if you only want to use the Webhook Trigger for triggering purposes and not for data delivery, you may also send an empty body.

## Using Webhook Trigger Data

If you use the Webhook Trigger to both trigger and deliver data to Qbilon, you will probably want to process the data. To do so, it is highly recommended that you create your own [Custom Tasks](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/index). This allows you to fetch the data delivered by the webhook via a simple call to the data endpoint of your Task Orchestrator.

To do this, you will need the following data to identify the correct Webhook Trigger payload to fetch and authenticate against the Task Orchestrator endpoint:

1. Acquire the host URL of your Task Orchestrator via the environment variable `QB_ORCHESTRATOR_HOST`.
2. Acquire the ID of the workflow/automation in which your task is running via the environment variable `QB_WORKFLOW_ID`.
3. Acquire an authentication token that lets you authenticate against the Task Orchestrator endpoint (see example code below).
4. Make a `GET` request to the following URL: `<QB_ORCHESTRATOR_HOST>/webhooks/resource/workflow/<QB_WORKFLOW_ID>`. You need to send the authentication token in the `AUTHENTICATION` header of that request.

The response of this endpoint will look like this:

```jsonc theme={null}
{
  "data": {...} // your json data object that you've sent to the Webhook Trigger URL
}
```

From that point on, you can do whatever you want with the provided data.

A simplified JavaScript example of this could look like this:

```javascript theme={null}
import fetch from 'node-fetch';
import { readFileSync } from 'fs';

// Qbilon Environment Variables
const host = process.env.QB_ORCHESTRATOR_HOST;
const wfid = process.env.QB_WORKFLOW_ID;
const token = readFileSync('/tmp/task-authentication')
const auth = `Bearer ${token}`

async function main() {
  try {
    // Fetch Webhook Trigger data
    const response = await fetch(`${host}/webhooks/resource/workflow/${wfid}`, {
      method: 'GET',
      headers: {
        'Authorization': auth,
        'Content-Type': 'application/json'
      }
    });
    const data = await response.json().data;
    // do something with that data
    // ...

  } catch (error) {
    console.log('Error', error);
  }
}

main();
```

> [!NOTE]
>
> This code only works within the context of a custom task.

### Deleting Webhook Triggers

You may want to delete your webhook triggers at some point, such as when they are no longer in use. To delete a webhook trigger, go to the `Webhooks` section in `Automations` and click the trash can icon next to the webhook you want to delete. Please note that webhooks currently in use by an automation cannot be deleted.

### Limitations

Currently there is a rate limit in place in order to avoid duplicated automation runs: A webhook may only be called once per minute, otherwise it will return a `429` response code. This is a per webhook limit, not per all webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.