The WebHook Trigger

Overview

A Playbook Trigger is an event that initiates the actions defined within a Playbook in ThreatConnect^® to occur. The WebHook Trigger creates an HTTPS endpoint that can process nearly any piece of information that can be sent via HTTP. This functionality is useful for building integrations and getting disparate systems to interact via Playbooks. For example, a SIEM can post a series of Indicators to the URL provided by the WebHook Trigger, the Playbook containing the Trigger can enrich the Indicators with additional context, and then the context can be sent back to the same URL.

The Trigger’s endpoint can be viewed on the Playbooks screen under the name of the Playbook containing the Trigger, as well as by hovering the cursor over the icon on the Trigger box in the design pane of the Playbook Designer. See the “Triggers” section of Parts of a Playbook for more information.

Before You Start

Creating a New WebHook Trigger

1. On the top navigation bar, click Playbooks to display the Playbooks screen.
2. Create a new Playbook or open an existing one.
3. Click Triggers on the side navigation bar of the Playbook Designer to view all available Triggers (Figure 1). 

    

4. Select WebHook from the External menu to add a WebHook Trigger to the design pane (Figure 2). 

    

5. Double-click the Trigger. The Configure section of the Edit Trigger pane will be displayed on the left side of the screen (Figure 3).
   Note

   Click the Display Documentation icon at the upper-right corner of the Edit Trigger pane to view information about the Trigger, including a description of the Trigger, its input parameters, and its output variables.
   

    

   • WebHook Name: Enter a name for the Trigger.
   • Path: A unique Trigger URL is generated automatically for each use of the Trigger. If desired, click in the box to edit the link’s universally unique identifier (UUID) path.
     Note

     If a custom UUID path entered in the Path parameter is already in use, a warning message stating “Already in use” will be displayed, and the NEXT button will be disabled.
   • Timeout: By default, the Trigger’s timeout length (that is, the amount of time the Trigger can run before timing out) is set to 5 minutes. Click in the box to edit this value, if desired.
6. Select the Enable Basic Authentication checkbox to provide a custom username and password (Figure 4). 

    

7. Select the Enable Data Caching checkbox to allow the Playbook to use a cache when making multiple requests that are the same to a WebHook Trigger (Figure 5). Data caching is used to improve performance and reduce the load on Playbook servers. When a cache key is found from a request, the response from the cache is used instead of running the full Playbook. Enabling this feature can reduce Playbook execution response times from minutes to milliseconds, depending on the specific Playbook logic. 

    

   • Minutes before cache key is purged: Enter the number of minutes before a key will be purged from the cache and a new Playbook execution will occur.
   • Record Metrics: Select this checkbox to record when a Playbook cache was hit, when it was missed, and the hit ratio and plot these metrics on a dashboard card.
   • Compose Cache Key from HTTP Request:A cache key helps the system decide whether it should pull the response from the cache or run the Playbook as a unique request. At least one of the following values must be defined or selected for a cache key:
     • Include Method: Select this checkbox when an HTTP method should be used to construct the cache key.
     • Include Body: Select this checkbox when an HTTP body should be used to construct the cache key.
     • Query Parameters: Enter query parameter names in the HTTP request that should be used to construct the cache key, and then click the Plus icon to add them to the Trigger.
     • Header: Enter header names in the HTTP request that should be used to construct the cache key, and then click the Plus icon to add them to the Trigger.
   • Click the NEXT button.
8. The Response Header section of the Edit Trigger pane will be displayed (Figure 6). The Response Header is the header on the message that will be displayed after the Playbook has run. 

    

   • Response Code: Enter the HTTP response code that will show with the Response Body when the Playbook is run.
   • Response Header: Enter the header as a key/value pair, and then click the Plus icon to add it to the Trigger.
     Note

     You can use variables in the Response Code and Response Header parameters.
   • Click the NEXT button.
9. The Response Body section of the Edit Trigger pane will be displayed (Figure 7). The Response Body is the message that will be displayed after the Playbook execution is complete. 

    

   • Body: Enter the text (HTML or plain text) that will be the Trigger’s response when it is run.
     Note

     You can use variables in the Response Body parameter.
   • Click the SAVE button.
10. Hover the cursor over the Hashtag icon at the upper-left corner of the Trigger in the design pane to display a list of output variables, which are values that the Trigger can send to other Apps and Operators (Figure 8). 

     

11. Click the Menu  icon at the upper-right corner of the Trigger to edit, disable, clone, or delete the Trigger (Figure 9).

     

Now you can continue to build out and then execute the Playbook.

Configuring the Playbook IP Address Access Filter

The Playbook IP Filter specifies the IP addresses that can send requests to WebHook Triggers. Follow these steps to configure the Playbook IP Filter for an Organization:

1. Log into ThreatConnect with an Organization Administrator account.
2. On the top navigation bar, hover the cursor over Settings and select Org Settings. The Organization Settings screen will be displayed with the Membership tab selected.
3. Click the Settings tab. The Settings screen will be displayed (Figure 10). 

    

4. In the Playbook IP Filter section, click Edit next to the Click here to enter a filter for IP Addresses text. A text box will be displayed (Figure 11). 

    

   • In the text box, enter any IP addresses or IP address ranges that will be allowed to send a request to WebHook Triggers, separating multiple values with commas.
   • Click Save to save additions or changes to the Playbook IP Filter.
     Note

     Users attempting to trigger a Playbook from IP addresses not on the filter list will receive an error message.

ThreatConnect^® is a registered trademark of ThreatConnect, Inc.

20097-01 v.04.B