--- title: "The WebHook Trigger | ThreatConnect" slug: "the-webhook-trigger" description: "This article describes how to configure the WebHook Trigger in a ThreatConnect Playbook. This Trigger creates an HTTPS endpoint that can process nearly any piece of information that can be sent via HTTP." tags: ["Orchestration and Automation"] updated: 2024-12-05T13:28:18Z published: 2024-12-05T13:28:18Z canonical: "knowledge.threatconnect.com/the-webhook-trigger" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.threatconnect.com/llms.txt > Use this file to discover all available pages before exploring further. # The WebHook Trigger ## Overview A Trigger is an event that initiates the actions defined within a Playbook in ThreatConnect®. 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](https://knowledge.threatconnect.com/docs/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. You can view a WebHook Trigger’s endpoint URL on the [**Playbooks** screen](https://knowledge.threatconnect.com/docs/the-playbooks-screen) under the name of the Playbook containing the Trigger. You can also view this URL in the [Playbook Designer](https://knowledge.threatconnect.com/docs/the-playbook-designer) by hovering the cursor over the **Information**![Playbook Trigger Information icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Trigger%20Information%20icon.png)icon on the Trigger box in the design pane. NoteThe Webhook Service Trigger is a custom WebHook Trigger. See [*Playbook Services*](https://knowledge.threatconnect.com/docs/playbook-services) for more information. ## Before You Start ### User Roles - To view Playbooks with a WebHook Trigger, your user account can have any [Organization role](https://knowledge.threatconnect.com/docs/organization-roles). - To add the WebHook Trigger to Playbooks, your user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer. - To execute Playbooks with a WebHook Trigger, your user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer. - To configure the Playbook IP Filter for an Organization, your user account must have an Organization role of Organization Administrator. ### Prerequisites - To have access to Playbooks, turn on the Playbooks system setting for your ThreatConnect instance on the **System Settings**screen (must be a System Administrator to perform this action). ## Adding a WebHook Trigger to a Playbook Follow these steps to add a WebHook Trigger to a Playbook and configure the Trigger: 1. Click **Playbooks** on the top navigation bar in ThreatConnect to open the **[](https://knowledge.threatconnect.com/docs/the-playbooks-screen)** [](https://knowledge.threatconnect.com/docs/the-playbooks-screen)[**Playbooks**screen](https://knowledge.threatconnect.com/docs/the-playbooks-screen)[](https://knowledge.threatconnect.com/docs/the-playbooks-screen)**[](https://knowledge.threatconnect.com/docs/the-playbooks-screen)**. [](https://knowledge.threatconnect.com/docs/the-playbooks-screen#creating-playbooks) 2. [Create a new Playbook](https://knowledge.threatconnect.com/docs/the-playbooks-screen#creating-playbooks) or open an existing one. 3. Click![Playbook Designer Triggers icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Designer%20Triggers%20icon.png)**Triggers** on the side navigation bar of the [Playbook Designer](https://knowledge.threatconnect.com/docs/the-playbook-designer) to view all available Triggers. Then select **WebHook** in the **External** menu to add a WebHook Trigger to the design pane (Figure 1). ![Figure 1_The WebHook Trigger_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%201_The%20WebHook%20Trigger_7.7.1.png) 4. Double-click the WebHook Trigger in the design pane to open the **Edit Trigger**pane. 5. Fill out the fields on the **Configure**step (Figure 2) as follows:HintClick **Display Documentation**![Playbooks_Display Documentation icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbooks_Display%20Documentation%20icon.png)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.![Graphical user interface, text, application Description automatically generated](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%202_The%20WebHook%20Trigger_7.7.1.png) - **WebHook Name**: Enter a name for the Trigger. - **Path**: A unique Trigger endpoint URL is generated automatically for each use of the Trigger. If desired, edit the URL’s universally unique identifier (UUID) path.NoteIf you enter a custom UUID path that is already in use in the **Path** parameter, a warning message stating “Already in use” will be displayed, and the **NEXT** button will be grayed out. - **Timeout**: Set the Trigger’s timeout length (that is, the amount of time the Trigger can run before timing out). The default timeout length is 5 minutes. - **Enable Basic Authentication**: (Optional) Select this checkbox to [enable basic authentication](/docs/the-webhook-trigger#enabling-basic-authentication) for the Trigger. - **Enable Data Caching**: (Optional) Select this checkbox to [enable data caching](/docs/the-webhook-trigger#enabling-data-caching) for the Trigger. 6. Click **NEXT**to proceed to the **Response Header**step. 7. (Optional) Fill out the fields on the **Response Header**step (Figure 3) as follows: ![Graphical user interface, text, application Description automatically generated](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%203_The%20WebHook%20Trigger_7.7.1.png) - **Response Code**: (Optional) Enter the HTTP response code that will show with the Trigger’s response body after the Playbook is run. - **Response Header**: (Optional) Enter the header as a key/value pair, and then click **Add****![Plus icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Plus%20icon_Black.png)**.HintYou can use variables in the **Response Code** and **Response Header** parameters. 8. Click **NEXT**to proceed to the **Response Body**step. 9. (Optional) In the **Body**parameter, enter the message that will be displayed after the Playbook execution is complete (Figure 4). You may use HTML or plain text, as well as Playbook variables, when creating the response body message. ![Graphical user interface, text, application, Teams Description automatically generated](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%204_The%20WebHook%20Trigger_7.7.1.png) 10. Click **SAVE**on the **Edit Trigger**pane to save the Trigger’s configuration. Now you can continue to [build out](https://knowledge.threatconnect.com/docs/designing-a-playbook) and then [execute](https://knowledge.threatconnect.com/docs/executing-a-playbook#playbooks-with-a-useraction-trigger) the Playbook. When building the Playbook, you can interact with the following elements along the top of the WebHook Trigger in the design pane to view more information about and manage the Trigger: - Hover the cursor over the **Hashtag**![Playbook Trigger Hashtag icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Trigger%20Hashtag%20icon.png)icon at the upper-left corner of the Trigger to view a list of output variables, which are values that the Trigger can send to other [Apps and Operators](https://knowledge.threatconnect.com/docs/parts-of-a-playbook) in the Playbook. - Hover over the **Information**![Playbook Trigger Information icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Trigger%20Information%20icon.png)icon at the upper-left corner of the Trigger to view the Trigger’s endpoint URL. - Click the **Menu**![Playbook Trigger Menu icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Trigger%20Menu%20icon.png)icon at the upper-right corner of the Trigger to open a menu with options to edit, disable, clone, and delete the Trigger. ### Enabling Basic Authentication To enable [basic authentication](https://datatracker.ietf.org/doc/html/rfc7617) for a WebHook Trigger, select the **Enable Basic Authentication**checkbox on the **Configure**step of the **Edit Trigger**pane (Figure 2). Then enter the username and password to use for basic authentication (Figure 5). ![Figure 5_The WebHook Trigger_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%205_The%20WebHook%20Trigger_7.7.1.png) ### Enabling Data Caching 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. To allow the Playbook to use a cache when making multiple requests that are the same to a WebHook Trigger, select the **Enable Data Caching**checkbox on the **Configure**step of the **Edit Trigger**pane (Figure 2). Then configure the following data caching settings on the **Configure**step (Figure 6): ![](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%206_The%20WebHook%20Trigger_7.7.1.png) - **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](https://knowledge.threatconnect.com/docs/dashboards) 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 **Add![](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Plus%20icon_Black.png)**. - **Header**: Enter header names in the HTTP request that should be used to construct the cache key, and then click **Add![](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Plus%20icon_Black.png)**. ## 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. Hover over **Settings![Settings icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Settings%20icon.png)**on the top navigation bar in ThreatConnect and select **Org Settings**. 3. Select the **Settings** tab on the **Organization Settings**screen. 4. In the**Playbook IP Filter** section on the **Settings**tab, click **Edit**![Pencil icon_Light gray](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Pencil%20icon_Light%20gray.png)next to the **Click here to enter a filter for IP Addresses**text to display a text box where you can configure the Playbook IP Filter (Figure 7). ![Graphical user interface, application, Teams Description automatically generated](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%207_The%20WebHook%20Trigger_7.7.1.png) 5. 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. Then click **Save**![Save icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Save%20icon.png)to save additions or changes to the Playbook IP Filter.NoteUsers 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.05.A ## Related - [Executing a Playbook](/executing-a-playbook.md) - [Parts of a Playbook](/parts-of-a-playbook.md) - [The Playbook Designer](/the-playbook-designer.md)