--- title: Using Webhook Triggers in Swimlane Turbine slug: using-webhook-triggers-in-swimlane-turbine docTags: createdAt: 2025-08-11T11:13:48.000Z --- Webhooks in Turbine enable seamless real-time communication by facilitating data exchange between third-party services and Turbine records. Webhooks act similarly to API callbacks, allowing playbooks to receive and process data without complex polling mechanisms. As an orchestrator, you can easily configure a webhook, generating a unique URL to integrate a playbook with web applications for automated data processing. Starting in **Turbine 26.2.0**, you can choose how incoming webhook **request bodies** are parsed on **Configure > Outputs** instead of relying only on **Content-Type** auto-detection. See [Payload Format Options](https://docs.swimlane.com/using-webhook-triggers-in-swimlane-turbine#payload-format-options) and [Webhook Triggers (Classic)](docId\:mc6VC88AQ2cldzoV7-xt2). Starting in **Turbine 26.4.0**, you can configure what the **caller receives** when the webhook URL is invoked — an optional **HTML** landing page for browser users, or a custom **JSON** body for API clients. See [Configure Webhook Response](docId\:BE3iKVBsY_HVvNdx3_rUU). ## Viewing Existing Webhooks To view existing webhooks in Turbine: 1. Navigate to **ORCHESTRATION** in the platform. 2. Click **Webhooks**. You can toggle the **Disabled** button to enable or disable a webhook. Click a webhook to view or modify its settings and logs. The **Filter by name** option helps you quickly find a specific webhook. ## Create Webhook Triggers One common use of webhooks is to ingest or push data, such as importing alerts into a playbook. To configure a webhook trigger: In a playbook, from the Add panel, click and drag **Catch Webhook** to the canvas. Hover over the plus icon to add it to the canvas. The Trigger panel displays to the right of the canvas, where you can configure the webhook trigger. ### Edit Webhook Settings To configure webhook-specific settings such as the URL, authentication, or the HTTP response returned to callers: 1. In the Trigger panel, click **Edit Webhook**. 2. Use the dialog tabs: - **Settings** — webhook title, description, URL, enable/disable, and authentication. - **Advanced** — optional **Webhook Response** (HTML landing page or JSON body). See [Configure Webhook Response](docId\:BE3iKVBsY_HVvNdx3_rUU). - **Logs** — incoming request history. 3. Click **Save** or **Save and Close**. :::hint{type="info"} **Configure → Outputs → Additional Options** still controls how Turbine **parses the incoming request body**. **Edit Webhook → Advanced** controls the **outgoing HTTP response** to the caller. These are separate settings. **Advanced** appears only on **Canvas** webhooks. On **Orchestration → Webhooks**, a webhook linked to a Canvas playbook opens the new Edit Webhook dialog. A classic webhook opens the previous dialog, without **Advanced**. ::: ## Configure Webhook Response Starting in **Turbine 26.4.0**, the **Advanced** tab on **Edit Webhook** includes **Webhook Response**. Use **HTML** when a human opens the webhook URL in a **browser**. Use **JSON** or **Default** when Slack, Teams, or another client calls the webhook without opening a browser. The feature is **optional**. Existing webhooks keep the legacy empty response until you change **Response Format**. Leave **Default** to preserve current behavior. ### Open Webhook Response 1. On the canvas, select the **Catch Webhook** trigger. 2. In the Trigger panel, click **Edit Webhook**. 3. Open the **Advanced** tab. 4. Under **Webhook Response**, set **Response Format**. | Response Format | What the caller receives | | --------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Default** | Legacy behavior: empty response body (backward compatible). | | **HTML** | An HTML landing page. Turbine starts from a styled **Request Received** template you can edit. | | **JSON** | A JSON response body. Turbine starts from `{"message":"Request received and will be processed.","status":"accepted"}`. | :::hint{type="warning"} Click **Save** or **Save and Close** after changing the response. Unsaved Advanced changes are not returned to callers. ::: ### HTML landing page Use **HTML** only when someone opens the webhook URL in a browser and needs a confirmation page. Slack and Teams do not display the HTML landing page. 1. Set **Response Format** to **HTML**. Authentication is not required to save this format. 2. Edit the HTML in the **Code** editor, or leave the default template. 3. Optionally insert dynamic values from the **incoming request**. See [Add Expression](docId\:BE3iKVBsY_HVvNdx3_rUU). 4. Review the live **Preview** pane before saving. If a **referenced** field shows as `undefined`, add that field to **Context Data**. Static text without references does not change. 5. Click **Save** or **Save and Close**. **HTML security notice (UI):** Request data (`$event.data.*`) comes from the caller and is untrusted. Use it only as plain text in your HTML. Do not put it in attributes, URLs, or scripts. **Authentication:** HTML does not require webhook authentication. You can save an HTML, JSON, or Default response with or without authentication on the **Settings** tab. Use authentication when you want to restrict who can invoke the webhook. Callers that cannot send credentials, such as some Slack button callbacks, can still reach the webhook when authentication is off. **Character limit:** The response body cannot exceed **10000** characters. The editor shows **Max character limit exceeded** when the limit is reached. ### JSON response Use **JSON** when API clients or automation expect a structured acknowledgment. 1. Set **Response Format** to **JSON**. 2. Edit the JSON body in the **Code** editor. 3. Optionally insert incoming-request fields or expressions. See [Add Expression](docId\:BE3iKVBsY_HVvNdx3_rUU). 4. Confirm the body is valid JSON. Invalid JSON shows **Invalid JSON in body** in **Preview**. 5. Review **Preview**, then click **Save** or **Save and Close**. The **10000**-character limit also applies to JSON bodies. ### Add Expression Use **Add Expression** to insert a dynamic value into the HTML or JSON template. - Only `$event.data.*` is supported. That path is incoming request data (`body`, `headers`, `url`, `method`, and nested request fields). - These expressions are not the same as **Add Expression** in webhook **Filters** or later playbook actions. - Playbook properties and assets cannot be used in webhook response expressions. **Add Playbook Property** still inserts a field from the incoming webhook event (for example `$event.data.body`). Despite the button label, it does not insert playbook properties. ### Preview and Context Data The Advanced editor includes: | Control | Purpose | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Code** | Edit the HTML or JSON response template. | | **Context Data** | Sample JSON shaped like webhook event data (`body`, `headers`, `url`, `method`) used only to drive **Preview**. It is not used at runtime. | | **Preview** | Renders the interpolated response for the current template and context data. | Update **Context Data** when you want Preview to reflect a realistic incoming payload, then confirm the landing page or JSON looks correct before you save. :::hint{type="warning"} **Incoming request data only** Webhook response can use data from the incoming HTTP request. It cannot use **assets** or **playbook properties**. **Preview** interpolates from **Context Data**, not from a live request. If a referenced field is missing from Context Data, **that reference** shows `undefined`. Unreferenced static text is unchanged. Copy a webhook event into Context Data to resolve references in Preview. At runtime, the same references resolve from the incoming request. ::: ### When to use each format | **Scenario** | **Recommended format** | | ---------------------------------------------------------------------- | ----------------------- | | Human opens the webhook URL in a browser (for example an email link) | **HTML** | | Slack or Teams action that calls the webhook without opening a browser | **JSON** or **Default** | | Machine or API client needs a parseable acknowledgment | **JSON** | | No change from pre-26.4.0 behavior | **Default** | ::::hint{type="info"} There is no separate Content-Type override control in the UI. Choosing **HTML** always returns :::Iframe{code=""} ::: text/html. Slack and Teams do not render that page. Choosing **JSON** returns :::Iframe{code=""} ::: application/json. **Default** keeps the legacy empty body. :::: ### Add Authentication Webhooks support two authentication methods that can be used independently or together: ### Basic Authentication 1. Expand the **Basic Authentication** section. 2. Provide: - **Username**: The username for HTTP Basic Authentication - **Password**: The password for HTTP Basic Authentication **Note:** Basic Authentication uses the standard HTTP `Authorization` header with the `Basic` scheme. The username and password are base64-encoded. ### Shared Secret Authentication 1. Expand the **Shared Secret Authentication** section. 2. Configure the following: - **Secret**: The secret value to verify incoming requests - **Secret Format**: Choose how the secret is formatted: - **plaintext**: The secret is sent as plain text (default) - **base64**: The secret is base64-encoded - **jwt**: The secret is a JWT token - **Secret Location**: Where to extract the secret from the incoming request: - **Request Header**: Extract from an HTTP header - **Header Name**: The name of the header (default: `Authorization`) - **Auth Scheme**: The scheme for Authorization header (default: `Bearer`) - **Request Query Parameter**: Extract from a URL query parameter - **Parameter Name**: The name of the query parameter - **Request Body**: Extract from the JSON request body - **Field Name**: The name of the field containing the secret **Note:** If both Basic Authentication and Shared Secret Authentication are configured, both must pass for the request to be authenticated. If no authentication is configured, the webhook accepts anonymous requests. ### Webhook Logs - View webhook request logs to verify that payloads are being received. - Use the Word Wrap toggle for better readability. - Click Jump to date to find logs for a specific time window. **Note:** Use the Logs tab to troubleshoot issues such as missing payloads or authentication failures. This is especially useful when testing new integrations. ### Configuring Webhook Events and Mapping Outputs To configure the webhook, fill in the following fields: After creating your webhook and generating the URL, send a test payload to the URL from your third-party tool (for example, SIEM or CRM). Then follow these steps to configure how your playbook uses the data: 1. In the **Trigger** panel, click **Configure**. 2. Navigate between the available tabs: - **Webhook Events** – View incoming webhook events triggered by payloads sent to the URL. - **Outputs** – Lists available output fields from payloads and **payload format options** (26.2.0+). - **Filter** – Define logic to determine when the playbook should run using conditions based on payload fields. ### Payload Format Options On the **Outputs** tab, under **Additional Options**, select 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**. **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**. | Click **Apply** on the configuration dialog to save a changed format to the webhook sensor. The format applies to the **next incoming webhook** after you apply. Send a new test payload to the webhook URL to verify parsing with the updated format. :::hint{type="info"} Unlike the HTTP Request **Test** tab, webhook payload format is stored on the webhook sensor when you click **Apply** on the **Configure** dialog. Incoming requests use the saved format, not an unsaved selection in the dialog. ::: To map values from an incoming webhook payload: 1. Go to the **Webhook Events** tab. 2. Expand any event: - You can copy the result from the **Result** tab. - Click **Discovered Outputs** to expand and view available fields from the payload. 3. Select the desired fields and click **Add selected to outputs**. 4. These fields will then appear in the **Outputs** tab for mapping in downstream actions. ## Webhook Outputs When a webhook receives a request, it provides the following output data that can be accessed in your playbook: ### Standard Webhook Outputs - `url`: An object containing URL components: - `href`: The full URL of the request - `protocol`: The protocol used (for example, `http`, `https`) - `hostname`: The hostname of the request - `port`: The port number (if specified) - `pathname`: The path portion of the URL - `query`: An object containing query parameters as key/value pairs - `hash`: The hash portion of the URL (if present) - `headers`: An object containing all HTTP headers from the request as key/value pairs - `body`: The request body after parsing. Type and shape depend on the payload format option on the **Outputs** tab (object when parsed as JSON, string when raw text, key/value pairs when URL-encoded). - `method`: The HTTP method used (`GET` or `POST`) ### Accessing Webhook Data in Playbooks You can access webhook data in downstream actions using the `$event.data` prefix: **Examples:** **Note:** The webhook outputs structure matches the incoming request. If you've mapped specific fields to outputs using the **Discovered Outputs** feature, those fields will also be available directly in the outputs schema. ## Webhook Filtering You can configure filters to control when your playbook runs based on webhook payload data: 1. In the **Trigger** panel, click **Configure**. 2. Navigate to the **Filter** tab. 3. Build filter conditions based on payload fields: - Select fields from the webhook payload (body, headers, query parameters, and so on) - Choose filter operators (equals, contains, greater than, and so on) - Set filter values - Combine multiple conditions using AND/OR logic **Example Filter:** Only trigger the playbook when `body.severity` equals `"High"`: - Field: `body.severity` - Operator: `equals` - Value: `"High"` **Note:** Filters are evaluated before the playbook runs. If the filter conditions are not met, the playbook will not execute, but the webhook event will still be logged. ## Webhook Use Cases Below are some examples demonstrating how webhooks can facilitate real-time automation within Turbine, integrating external systems into your playbooks. ### Example 1: Ingesting Security Alerts from an External System **Scenario:** You use a Security Information and Event Management (SIEM) platform like Splunk or IBM QRadar. When an alert is generated, you want to ingest this information into Turbine to automatically start a playbook for alert triage and response. **Steps:** 1. Create a webhook in Turbine called "Ingest Alert". 2. Generate the webhook URL and configure the SIEM to send alert data to this URL. 3. Map fields from the webhook payload to appropriate fields in Turbine. 4. **Note:** After sending a test payload to the webhook URL, go to the **Webhook Events** tab and click **Discovered Outputs** to view the payload structure. From there, select relevant fields and click **Add selected to outputs**. These outputs will then appear in the **Outputs** tab and become available for mapping in downstream playbook actions. In the playbook, the following actions occur: - Parse the alert data - Create a new incident in Turbine - Assign the incident to an analyst - Trigger automated response actions, such as disabling accounts **Example Payload:** ### Example 2: Automating Customer Support with a Webhook from a CRM System **Scenario:** You use a customer relationship management (CRM) tool like Salesforce or HubSpot. You want to automatically trigger actions in Turbine when new customer support tickets are submitted through the CRM. **Steps:** 1. Set up a webhook in the CRM system to send new ticket data to Turbine. 2. Configure the webhook trigger in Turbine to receive the ticket details. In the playbook, the following actions occur: - Log the ticket into Turbine - Notify the support team - Assign the ticket to an available support agent **Example Payload:** ### Example 3: Webhook for Monitoring E-commerce Orders **Scenario:** You operate an e-commerce platform that integrates with Turbine to track and automate order processing. When a new order is placed, the webhook triggers a playbook that processes the order and sends confirmation emails. **Steps:** 1. Set up a webhook to trigger when a new order is placed. 2. Configure the webhook in Turbine to receive the order details. In the playbook, the following actions occur: - Record the order in Turbine - Send confirmation emails - Update the inventory system **Example Payload:** ### Example 4: Webhook for GitHub Integration **Scenario:** You use GitHub for version control and want to trigger automated actions in Turbine when certain GitHub events occur, such as a pull request or new commit. **Steps:** 1. Set up a webhook in GitHub to trigger on events like pull requests. 2. Configure the webhook in Turbine to receive the event details. In the playbook, the following actions occur: - Review the pull request - Run automated tests - Notify the team if tests pass **Example Payload:** ### Example 5: Automated Data Backup with Webhooks **Scenario:** You want to automatically back up datasets from a cloud application whenever a specific event occurs, such as when a file is updated. **Steps:** 1. Set up a webhook in the cloud application to trigger on file updates. 2. Configure the webhook in Turbine to receive the file details. In the playbook, the following actions occur: - Copy the file to a backup storage system - Log the backup event - Notify the admin team **Example Payload:** ## Best Practices - **Landing pages for people:** Prefer **HTML** only when the caller opens the webhook URL in a browser (for example an email link). Do not choose **HTML** for Slack or Teams actions that stay in the chat client. - **Keep API clients stable:** Prefer **JSON** (or **Default**) for automated callers that expect an empty body or a fixed JSON shape. - **Treat event data as untrusted in HTML:** Insert `$event.data.*` only as plain text. Do not place caller-controlled values in HTML attributes, URLs, or scripts. - **Preview before save:** Put sample request JSON in **Context Data** so Preview can resolve referenced `$event.data.*` values. Empty Context Data does not blank the Preview; only **referenced** fields show `undefined`. - **Authentication is optional for webhook response:** Configure authentication on **Settings** when you want to restrict callers. Do not treat it as required for HTML. - **Use Authentication:** Always configure authentication (Basic Auth or Shared Secret) for production webhooks to prevent unauthorized access. - **Use Shared Secrets for API Integrations:** When integrating with third-party APIs, use Shared Secret authentication with a secure secret value. - **Map Only Required Fields:** Use the **Discovered Outputs** feature to map only the fields you need, reducing complexity and improving performance. - **Test with Sample Payloads:** Send test payloads to your webhook URL before deploying to production to verify the payload structure and field mappings. - **Use Filters for Efficiency:** Configure filters to prevent unnecessary playbook executions when webhook events do not meet your criteria. - **Monitor Webhook Logs:** Regularly check webhook logs to verify that payloads are being received correctly and to troubleshoot authentication or parsing issues. - **Handle Missing Fields:** In your playbook actions, handle cases where expected fields might be missing from the webhook payload. - **Validate Payload Structure:** Use filters or conditional logic in your playbook to validate that required fields are present before processing. - **Secure Secrets:** Store authentication secrets securely and rotate them regularly. Never expose webhook URLs with authentication credentials in logs or documentation. - **Use Descriptive Names:** Give your webhooks descriptive titles and names to make them easy to identify and manage. ## Troubleshooting - **Caller still sees an empty response:** Confirm **Response Format** is **HTML** or **JSON**, then click **Save** or **Save and Close**. - **Max character limit exceeded:** Shorten the HTML or JSON body to **10000** characters or fewer. - **Preview shows Invalid JSON in body:** Fix JSON syntax on the **Code** tab. - **Preview shows Invalid Context Data:** Fix the sample JSON on the **Context Data** tab. - **Preview shows **`undefined`** on a referenced field:** That placeholder is in the template, and **Context Data** does not include it. Paste a sample webhook event into **Context Data**. Preview never uses a live request. - **Slack or Teams does not show the landing page:** **HTML** is rendered only in a browser. Use **JSON** or **Default** for those clients. If a Slack button must call the webhook without credentials, leave authentication off. - **Advanced tab missing:** Custom webhook responses apply to **Canvas** webhooks only. On **Orchestration → Webhooks**, a classic webhook opens the previous edit dialog. - **Webhook Not Receiving Requests:** - Verify the webhook is enabled (check the Enabled toggle) - Verify the webhook URL is correct and accessible - Check that the external system is configured to send requests to the correct URL - Review webhook logs for incoming requests - **Authentication Failures:** - Verify Basic Auth username and password match what the external system is sending - For Shared Secret Auth, verify: - The secret value matches exactly (case-sensitive) - The secret format (plaintext, base64, jwt) is correct - The secret location (header, query parameter, body) matches where the external system is sending it - Header names are correct (case-insensitive for standard headers) - Check webhook logs for authentication error messages - **Payload Not Parsing Correctly:** - On **Configure > Outputs**, under **Additional Options**, select a payload format that matches the sender (for example **URL Encoded params** for form posts, **Body as JSON** when **Content-Type** is missing, **Body as Raw Text** for non-JSON bodies) - Click **Apply** on the **Configure** dialog after changing the format, then send a new test payload - Review the webhook event in the **Webhook Events** tab to see the actual payload structure - Use **Discovered Outputs** to view available fields from the payload - **Format Change Does Not Apply:** - Click **Apply** on the **Configure** dialog after changing the option on **Outputs** - Send a new test payload — events received before **Apply** were parsed with the previous saved format - **Fields Not Available in Playbook:** - Ensure you've mapped fields to outputs using **Discovered Outputs** - Verify the field paths match the payload structure (for example, `body.fieldName` for nested fields) - Check that the webhook event was received successfully (view in **Webhook Events** tab) - **Playbook Not Triggering:** - Verify the webhook is enabled - Check filter conditions - if filters are configured, ensure the payload matches the filter criteria - Verify the playbook is published and active - Review webhook logs for any errors - **Query Parameters Not Accessible:** - Access query parameters using `$event.data.url.query.parameterName` - Verify query parameters are included in the webhook URL - Check that parameter names match exactly (case-sensitive) - **Headers Not Accessible:** - Access headers using `$event.data.headers['Header-Name']` or `$event.data.headers.headerName` - Header names are case-insensitive for standard HTTP headers - Verify the external system is sending the expected headers ```text { "file_id": "1A2B3C4D", "file_name": "financial-report.xlsx", "last_modified_time": "2024-10-18T16:00:00Z" } ```