Using Webhook Triggers in Swimlane Turbine

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" }