---
title: Webhook Triggers (Classic)
slug: webhook-triggers-classic
docTags: 
createdAt: 2025-08-11T11:13:46.000Z
---

Webhooks are a type of event stream that enables products, vendors, or services to push real-time communication in Turbine. They process and enrich data to send from third-party services and platforms to Turbine records.

Starting in **Turbine 26.2.0**, you can choose how the incoming webhook **request body** is parsed on **Configure > Outputs** instead of relying only on **Content-Type** auto-detection. Use this when a vendor sends JSON without a JSON content type, form-encoded data without the expected header, or raw text such as XML or syslog you will handle in playbook logic.

:::hint{type="warning"}
Click **Save** or **Save and Close** after making changes.
:::

## View Existing Webhooks

To view existing webhooks:

1. Navigate to **ORCHESTRATION**.
2. Click **Webhooks**.

From here you can toggle the **Enabled** button to enable or disable the webhook, or click the desired webhook to view settings and log information.

### Create Webhook Triggers

To create a webhook trigger, create a new playbook, upload a playbook, or search for an existing playbook.

1. On the playbook, click **Add a trigger**.
2. Click **Catch Webhook**.
3. On TRIGGER, enter a webhook title and click **Generate URL** or the webhook will not be created.

   ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/BddXOvMZoJWP0sQREsy8t_generate-webhook-url.png" size="64" width="800" height="420" darkWidth="800" darkHeight="420" position="center" showCaption="false"}

Once the **Generate URL** button has been clicked, the webhook's URL is generated in the **Webhook URL** field and the **Copy URL** link is enabled.

Next, you can edit the webhook settings.

### Edit Webhook Settings

To change webhook settings:

1. On TRIGGER, click **Edit Webhook**.
   On the SETTINGS tab, you can update the webhook title, add properties to authenticate the webhook requests, copy the URL, and enable/disable the webhook.

   ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/koysde8FWfYpkSDq_Xxlp_edit-webhook-settings-tab.jpg" size="62" width="800" height="345" darkWidth="800" darkHeight="345" position="center" showCaption="false"}

:::Paragraph{indent="1"}
On the LOGS tab, you can view the webhook logs, view by date, and enable/disable the webhook.
:::

::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/Ne6tfCz83ar4U7dNeQkpx_edit-webhook-logs-tab.png" size="64" width="800" height="346" darkWidth="800" darkHeight="346" position="center" showCaption="false" indent="2"}

2. Click **Save and Close** to save updates.
   If you do not need to edit your webhook, you can go straight to configuring.

## Configure Webhooks

:::hint{type="danger"}
Review [Create and Edit Playbook Inputs](docId:-LGnYDBJ4charvN4_9VKo) before configuring webhooks for best practices.
:::

You are ready to start the configuration process for your webhook. Click **Configure** to get started. The webhook configuration window has three tabs: Webhook Events, Outputs, and Map to Playbook Inputs.

**Webhook Events tab**

This tab shows the Event Type with a drop-down arrow, which shows you the webhook details, the result, and discovered outputs. Navigate to [Discovered Outputs and Testing](docId:0m_vna2tE15I4msHcDnJ1) for details on how to view and/or add discovered outputs, the agent/host for that webhook, the time the webhook was last received, and the numbered of triggered playbooks related to that webhook.

**Outputs tab**

This tab shows you all the outputs from the webhook. These are default property types. If you added any discovered outputs, then they show up with the **Delete** hyperlink. Any property types without that Delete hyperlink are part of the original returned inputs from the webhook.

Under **Additional Options**, select a payload format option to control how Turbine parses the incoming webhook **request body** into `$event.data.body`. The radio options are **Auto-detect**, **Body as JSON**, **Body as Raw Text**, and **URL Encoded params**. This setting controls parsing only; it does **not** change what the sending system posts or the **Content-Type** header on the request.

| Option                 | When to Use                                                                                                                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto-detect**        | Default. Turbine uses the request **Content-Type** header: form URL-encoded bodies are parsed as key/value pairs; other types use JSON parsing (same behavior as before 26.2.0).                                             |
| **Body as JSON**       | Always parse the body as JSON, regardless of **Content-Type**. Use when a vendor sends JSON without a JSON content type. **Body as JSON** supports JSON only; use **Body as Raw Text** for XML, RSS, or other non-JSON text. |
| **Body as Raw Text**   | Store the body as a string without parsing. Use for XML, syslog text, or other formats you will handle in playbook logic.                                                                                                    |
| **URL Encoded params** | Always parse the body as `application/x-www-form-urlencoded` key/value pairs, regardless of **Content-Type**. Use when a vendor sends form-encoded data without the expected header.                                         |

:::hint{type="info"}
Payload format options are on the **Configure** dialog **Outputs** tab (**Additional Options**), not on **Edit Webhook > Settings**. Click **Apply** on the configuration dialog to save a changed format to the webhook sensor. Send a new test payload after **Apply** to verify parsing. Unlike the HTTP Request **Test** tab, unsaved format changes do not affect incoming webhooks.
:::

**Map to Playbook Inputs tab**

Remember the important note on reviewing [Create and Edit Playbook Inputs](docId:-LGnYDBJ4charvN4_9VKo) for best practices? That is because on this tab, if you do not see any inputs, it is because your playbook currently does not have any inputs. You can add them, and they will display on this tab. And just like the action inputs, you can click **Add a property** to see the drop-down menu. You can add a playbook property or expression. Selecting **Playbook property** opens the property drawer where you can select the desired property to map.

**Filter tab**

The **Filter** tab allows you to apply a condition on event triggers allowing you to prevent the playbook execution unless the criteria is met. You can select a condition type from the drop-down next to **MATCHES**.

::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/O1lcUVbpfdjkEzdFCpVJu_filteringwebhooks.png" size="72" width="800" height="293" darkWidth="800" darkHeight="293" position="center" showCaption="false"}

### $event.data Properties

Here is the list of top-level properties that are defined on the $event.data object:

- **url** *(object)*: The URL components of the request.
  - **href**\*(string)\*: The full URL of the request.
  - **protocol**\*(string)\*: The protocol used for the request.
  - **hostname**\*(string)\*: The hostname of the request.
  - **port**\*(integer)\*: The port of the request.
  - **pathname**\*(string)\*: The pathname of the request.
  - **query**\*(object)\*: The query parameters of the request as key/value pairs.
  - **hash**\*(string)\*: The hash of the request.
- **headers** *(object)*: The headers of the request as key/value pairs.
- **body** *(null|array|boolean|number|object|string)*: The request body after parsing. Type and shape depend on the payload format option on the **Outputs** tab.

### Authenticate Webhooks

To configure webhook authentication settings:

1. On **TRIGGER**, click **Edit Webhook**.
2. On the **SETTINGS** tab, click **Add a property**, then click **Authentication**.

   ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/YCVpLV5xJcXyVtadTXBaV_webhook-add-a-property.png" size="68" width="800" height="353" darkWidth="800" darkHeight="353" position="center" showCaption="false"}

:::Paragraph{indent="1"}
The **Authorization** property displays with a sub-property option.
:::

## Basic Authentication

1. Select **Basic Authentication**.
   Basic authentication specifies the credentials to be sent in and verified from the **Authorization** header using the basic authentication scheme.
2. Complete the **Username** and **Password** fields, and click **Save**.
   Mirror the username and password with your third-party system.

   ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/etEa0T88Thmv9YFizQPqP_webhook-basic-auth.png" size="54" width="800" height="667" darkWidth="800" darkHeight="667" position="center" showCaption="false"}
3. To remove basic authentication, click the vertical ellipsis, then click **Remove**.

## Shared Secret Authentication

1. Select **Shared Secret Authentication**.
   Shared secret authentication specifies the credentials to be sent in and verified from one of the following locations in the webhook requests: header, body, or query parameter.
2. Complete the **Secret**, **Secret Format**, and **Secret Location** fields.

   ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/VF1XoR9sZpNKTc3NeALkC_webhook-shared-secret-auth-property.png" size="46" width="800" height="686" darkWidth="800" darkHeight="686" position="center" showCaption="false"}
3. To complete the **Secret Location**, click **Add a property**.
4. From the drop-down menu, select one of the following properties:
   - **Request Body** – extract the secret (Password) from the request body.
   - **Request Header** – extract the secret (Password) from the request header.
   - **Request Query Parameter** – extract the secret (Password) from a query parameter.
5. To remove these properties, click the vertical ellipsis, then click **Remove**.

## Troubleshooting Payload Format

| Symptom                                         | What to check                                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **body** is a string but you expected an object | On **Configure > Outputs > Additional Options**, select **Body as JSON** if the vendor sends JSON without a JSON **Content-Type**.                                                                    |
| **body** is parsed incorrectly as JSON          | Select **Body as Raw Text** for non-JSON payloads, or **URL Encoded params** for form posts without the expected header.                                                                              |
| Webhook request fails before the playbook runs  | With **Body as JSON**, the body must be valid JSON. Use **Auto-detect** or **Body as Raw Text** if the sender posts non-JSON content.                                                                 |
| Format change does not apply                    | Click **Apply** on the **Configure** dialog after changing the option. Send a new test payload to the webhook URL — existing events on **Webhook Events** were parsed with the previous saved format. |

## View Webhook Logs

1. On **TRIGGER**, click **Edit Webhook** and then click the **Logs** tab.
2. You can:

- View the logs.
- Enable or disable the webhook.
- Filter by date using **Jump to date**.