Using Webhook Triggers in Swimlane Turbine

16 min

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.

Viewing Existing Webhooks

To view existing webhooks in Turbine:

Navigate to ORCHESTRATION in the platform.

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 or authentication:

In the Trigger panel, click Edit Webhook.

In the Settings tab:

Copy the Webhook URL to use with external systems.

Add or update the description if needed.

Click the Enabled toggle to activate or deactivate the webhook.

Add Authentication

Webhooks support two authentication methods that can be used independently or together:

Basic Authentication

Expand the Basic Authentication section.

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

Expand the Shared Secret Authentication section.

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:

In the Trigger panel, click Configure.

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.

Filter – Define logic to determine when the playbook should run using conditions based on payload fields.

To map values from an incoming webhook payload:

Go to the Webhook Events tab.

Expand any event:

You can copy the result from the Result tab.

Click Discovered Outputs to expand and view available fields from the payload.

Select the desired fields and click Add selected to outputs.

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 (e.g., 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 JSON body of the request (parsed as an object)

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:

In the Trigger panel, click Configure.

Navigate to the Filter tab.

Build filter conditions based on payload fields:

Select fields from the webhook payload (body, headers, query parameters, etc.)

Choose filter operators (equals, contains, greater than, etc.)

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:

Create a webhook in Turbine called "Ingest Alert".

Generate the webhook URL and configure the SIEM to send alert data to this URL.

Map fields from the webhook payload to appropriate fields in Turbine.

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:

Set up a webhook in the CRM system to send new ticket data to Turbine.

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:

Set up a webhook to trigger when a new order is placed.

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:

Set up a webhook in GitHub to trigger on events like pull requests.

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:

Set up a webhook in the cloud application to trigger on file updates.

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

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 don't 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

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:

Verify the request body is valid JSON

Check that the Content-Type header is set to application/json

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

Fields Not Available in Playbook:

Ensure you've mapped fields to outputs using Discovered Outputs

Verify the field paths match the payload structure (e.g., 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

{
  "file_id": "1A2B3C4D",
  "file_name": "financial-report.xlsx",
  "last_modified_time": "2024-10-18T16:00:00Z"
}