Skip to main content
Skip table of contents

Webhook Configuration Guide

Webhook keys can be configured for data ingestion and remote command in the following tabs under the Configuration section in D3 SOAR:

  • Data Ingestion

  • Integrations

  • Utility Command

This document provides instructions on the unified webhook configuration process. The initial steps to access the webhook configuration settings may vary slightly in each of these configuration modules but the subsequent steps remain similar. Please refer to the respective documentation of these sections for instructions on how to initially access the webhook configuration settings.

To ensure secure transmission of webhook data, you have the option to authenticate requests using API keys or JSON web tokens (JWT). API keys are unique identifiers that are associated with your integration and are used to verify the authenticity and permissions of the incoming webhook data. Alternatively, JWT provides a more secure authentication mechanism by digitally signing the payload and including additional claims for enhanced security.

Reader Note

The JSON web token authentication method is disabled by default. To enable this authentication method, follow these steps:

  1. Go to the Configuration section.

  2. Navigate to Application Settings and select Web Config.

  3. Locate the "EnableEnhanceWebhookAuthentication" configuration key.

  4. Set the value of this key to True.

By modifying the configuration setting as mentioned above, you will enable the JSON web token authentication method. This will enhance the security of your webhook authentication process, ensuring that only authorized requests with valid JSON web tokens can access and interact with the system.

Event/Incident Intake

The webhook ingestion method allows an integration to send event or incident data (in JSON format) to be investigated in the D3 SOAR. This can be configured from the Data Ingestion and Integrations tabs under Configuration. Refer to the respective documents of each section for instructions on accessing the configuration settings.

Authentication Method: API Keys

a. You have the option to rename the key (only as the creator), assign or change the assigned user, view other created keys on the site accessible to your user account and regenerate existing keys.

b. Request URL: The request URL for the API request. The request URL is required for constructing the API request. You have the option to select a specific site and view the corresponding request URL.

c. Request Header Key: The request header key to authenticate the API request. The request header key is required for constructing the API request.

d. Request Header Value: The request header value to authenticate the API request. This is also known as the webhook or API key. The request header value is required for constructing the API request.

e. (Optional) Specify the JSON path within the retrieved data that contains the site(s) where you want to ingest the data. This parameter can be used alongside the Global List for Site Mapping parameter, which selects a global list containing the mapping information for the sites.

Reader Note

This option will only appear if you are configuring an API key that is shared across all client sites.

For example, suppose the retrieved data has the following structure:

JSON 
{
  "alerts": [
    {
      "data_type": "alert",
      "alert_id": "dac0ad8680-38b4-4222-b45e-ce47f41df82e_70-1",
      "case_id": "C200000007000",
      "criticality_calculated": "Low",
      "customer": {
        "name": "CE_Demo_Site_A",
        "id": "A"
      }
    },
    {
      "data_type": "alert",
      "alert_id": "dac0ad8680-38b4-4222-b45e-ce47f41df82e_80-1",
      "case_id": "C200000008000",
      "criticality_calculated": "Critical",
      "customer": {
        "name": "CE_Demo_Site_B",
        "id": "B"
      }
    }
  ]
}

The JSON path for this parameter could be $.customer.name or $.customer.id. If you input $.customer.name, the value of the key already directly represents the name of the site, eliminating the need to reference a global list. On the other hand, if you input $.customer.id, you can select a global list that maps the site ID values to the site names. Here's an example of what the global list might look like:

CODE 
[
  {
    "A": "CE_Demo_Site_A",
    "B": "CE_Demo_Site_B"
  }
]

By configuring this, the platform will ingest the data into the corresponding site based on the value specified in the JSON path.

f. (Optional) Select the global list that contains the mappings between the field value of the specified JSON path and the corresponding site names. This parameter is used in conjunction with the JSON Path for Site parameter.

Reader Note

This option will only appear if you are configuring an API key that is shared across all client sites.

g. (Optional) Select a Data Formatter to run a data formatter command on the incoming event after ingestion. Data formatter commands can be configured in Utility Command by checking the “Event/Incident Data Formatter” feature.

h. (Optional) Select an Event Playbook from the drop-down. This determines which event playbook will be run upon ingestion.

i. (Optional) Check the box to enable sequential event playbook processing for datasets with multiple alerts to streamline event and incident correlation. This option ensures alerts are processed in order, facilitating more streamlined event and incident correlation.

Reader Note

This option will only appear if you have selected an event playbook for the previous parameter.

For example, if two alerts share a case ID but different alert IDs, enabling sequential processing allows the second alert to correlate with the existing incident created for the first alert. This is particularly useful for datasets with alerts containing related information.

In another scenario, when alerts share an alert ID but have different severity levels, sequential processing updates the existing incident with the latest information instead of creating a new incident.

j. (Optional) Check the box to enable the automatic mapping of ingested events from the data source to MITRE tactics and techniques.

k. (Optional) Check the box to allow event automation rules to be applied for dismissing or escalating the ingested events from the data source.

Reader Note
The "Run Event Automation Rules" check box is not applicable for incident intake commands.

With all the necessary values, you can send a REST API request to execute the data ingestion command through Postman or other programs. The response of the API call will indicate the result of the command execution.

Authentication Method: JWT

a. You have the option to rename the key (only as the creator), view other created keys on the site accessible to your user account, and specify its visibility to all users.

b. Request URL: The request URL for the API request. The request URL is required for constructing the API request. You have the option to select a specific site and view the corresponding request URL if your key is shared to all internal or client sites.

c. Request Header Key: The request header key to authenticate the API request.

d. Header: The header typically consists of three parts: the signing algorithm being used, HMAC SHA256, the key id, and the type of the token, which is JWT. The header JSON object is required for generating the JWT.

e. Payload: Input the first-level keys of your request body data as the payload fields. For instance, for the sample request body data below, you should input Username, Site and CommandParams as the payload fields. After entering the key fields, copy the payload value using the copy button. This is required for generating the JWT.

JSON 
{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Start Time": "2020-09-01 00:44:45",
    "End Time": "2020-09-01 17:44:45",
    "Number of Event(s) Fetched": 5,
    "Search Condition": "search host=\"D3-Cyber-2\" | head 10",
    "Artifact": null
  }
}

f. Secret Key: Click and hold to reveal the secret key. This is only available if you are the creator or assigned user of the key.

g. (Optional) Specify the JSON path within the retrieved data that contains the site(s) where you want to ingest the data. This parameter can be used alongside the Global List for Site Mapping parameter, which selects a global list containing the mapping information for the sites.

For example, suppose the retrieved data has the following structure:

JSON 
{
  "alerts": [
    {
      "data_type": "alert",
      "alert_id": "dac0ad8680-38b4-4222-b45e-ce47f41df82e_70-1",
      "case_id": "C200000007000",
      "criticality_calculated": "Low",
      "customer": {
        "name": "CE_Demo_Site_A",
        "id": "A"
      }
    },
    {
      "data_type": "alert",
      "alert_id": "dac0ad8680-38b4-4222-b45e-ce47f41df82e_80-1",
      "case_id": "C200000008000",
      "criticality_calculated": "Critical",
      "customer": {
        "name": "CE_Demo_Site_B",
        "id": "B"
      }
    }
  ]
}

The JSON path for this parameter could be $.customer.name or $.customer.id. If you input $.customer.name, the value of the key already directly represents the name of the site, eliminating the need to reference a global list. On the other hand, if you input $.customer.id, you can select a global list that maps the site ID values to the site names. Here's an example of what the global list might look like:

JSON 
[
  {
    "A": "CE_Demo_Site_A",
    "B": "CE_Demo_Site_B"
  }
]

By configuring this, the platform will ingest the data into the corresponding site based on the value specified in the JSON path.

h. (Optional) Select the global list that contains the mappings between the field value of the specified JSON path and the corresponding site names. This parameter is used in conjunction with the JSON Path for Site parameter.

Reader Note

This option will only appear if you are configuring an API key that is shared across all client sites.

i. (Optional) Select a Data Formatter to run a data formatter command on the incoming event after ingestion. Data formatter commands can be configured in Utility Command by checking the “Event/Incident Data Formatter” feature.

j. (Optional) Select an Event Playbook from the drop-down. This determines which event playbook will be run upon ingestion.

k. (Optional) Check the box to enable sequential event playbook processing for datasets with multiple alerts to streamline event and incident correlation. This option ensures alerts are processed in order, facilitating more streamlined event and incident correlation.

Reader Note

This option will only appear if you have selected an event playbook for the previous parameter.

For example, if two alerts share a case ID but different alert IDs, enabling sequential processing allows the second alert to correlate with the existing incident created for the first alert. This is particularly useful for datasets with alerts containing related information.

In another scenario, when alerts share an alert ID but have different severity levels, sequential processing updates the existing incident with the latest information instead of creating a new incident.

l. (Optional) Check the box to enable the automatic mapping of ingested events from the data source to MITRE tactics and techniques.

m. (Optional) Check the box to allow event automation rules to be applied for dismissing or escalating the ingested events from the data source.

Reader Note

The "Run Event Automation Rules" check box is not applicable for incident intake commands.

Generating the Encoded JWT

Use the following Python script template to generate the encoded JWT using the PyJWT library and the HMAC SHA256 algorithm.

Reader Note

The provided Python script requires the PyJWT module to be installed. For more information, refer to Installation — PyJWT 2.6.0 documentation.

PY 
import jwt
import time

# set the payload of the JWT
payload = {
    "Site": "Security Operations",
    "Timestamp": time.time(),
    "Param1":"my_param_value"
}

jwt_header = {
    "alg":"HS256",
    "kid":"123",
    "typ":"JWT"
}

# set the secret key used to sign the JWT
secret_key = "my_secret_key"

# generate the JWT
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256", headers=jwt_header)

print(jwt_token)

  1. Replace the sample value of the payload variable with the payload array copied from D3 SOAR.

  2. Replace the sample value of the jwt_header variable with the header array copied from D3 SOAR.

  3. Replace the sample value of secret_key variable with the secret key copied from D3 SOAR.

  4. Run the script to generate the encoded JWT. After running the script, you will see the encoded JWT printed in the console. Copy this token and use it to authenticate your webhook request as needed.

With all the necessary values, you can send a REST API request to execute the event or incident ingestion command through Postman or other programs. The response of the API call will indicate the result of the command execution.

Remote Command

The D3 command API allows you to send requests to D3 SOAR to execute configured integration or utility commands via REST API.

Authentication Method: API Keys

a. You have the option to view other created keys on the site accessible to your user account and edit the name of the key.

b. Request URL: The request URL for the HTTP request. If you are configuring an integration command, use the dropdown menu to select a site. The request URL will be generated.

Reader Note

The "Select Site" dropdown is not applicable for utility commands.

c. Request Header Key: The request header key to authenticate the API request.

d. Request Header Value: The request header value to authenticate the API request. You may regenerate a new value by clicking Regenerate Key.

e. Request Body (Sample): A sample body data for the API request. Please note that the input parameters for different commands vary. Therefore, you will need to construct body data with the correct structure in your request. The provided sample body data is structured accordingly for the specific command. Using it as a template to build your body data is recommended.

Warning
The request body data must be structured accordingly to the command in order to send a successful request.

With all the necessary values, you can send a REST API request to execute the remote command through Postman or other programs. The response of the API call will indicate the result of the command execution.

Authentication Method: JWT

a. You have the option to rename the key, assign or change the assigned user, view other created keys on the site accessible to your user account and specify its visibility to all users. The assigned user will be recognized as the user when a command requires a user parameter.

b. Request URL: The request URL for the API request. The request URL is required for constructing the API request. You have the option to select a specific site and view the corresponding request URL.

c. Request Header Key: The request header key to authenticate the API request. The request header key is required for constructing the API request.

d. Header: The header typically consists of three parts: the signing algorithm being used, HMAC SHA256, the key id, and the type of the token, which is JWT. The header JSON object is required for generating the JWT.

e. Payload: For remote commands, the default payload fields are Timestamp, Site and Username. It is not required to input additional payload fields, although you have the option to do so. After entering the key fields, copy the payload value using the copy button. This is required for generating the JWT.

f. Secret Key: Click and hold to reveal the secret key. This is only available if you are the creator or assigned user of the key.

g. Request Body (Sample): A sample body data for the API request. Please note that the input parameters for different commands vary. Therefore, you will need to construct body data with the correct structure in your request. The provided sample body data is structured accordingly for the specific command. Using it as a template to build your body data is recommended.

Warning
The request body data must be structured accordingly to the command in order to send a successful request.

Generating the Encoded JWT

Use the following Python script template to generate the encoded JWT using the PyJWT library and the HMAC SHA256 algorithm.

Reader Note

The provided Python script requires the PyJWT module to be installed. For more information, refer to Installation — PyJWT 2.6.0 documentation.

PY 
import jwt
import time

# set the payload of the JWT
payload = {
    "Site": "Security Operations",
    "Timestamp": time.time(),
    "Param1":"my_param_value"
}

jwt_header = {
    "alg":"HS256",
    "kid":"123",
    "typ":"JWT"
}

# set the secret key used to sign the JWT
secret_key = "my_secret_key"

# generate the JWT
jwt_token = jwt.encode(payload, secret_key, algorithm="HS256", headers=jwt_header)

print(jwt_token)

  1. Replace the sample value of the payload variable with the payload array copied from D3 SOAR.

  2. Replace the sample value of the jwt_header variable with the header array copied from D3 SOAR.

  3. Replace the sample value of secret_key variable with the secret key copied from D3 SOAR.

  4. Run the script to generate the encoded JWT. After running the script, you will see the encoded JWT printed in the console. Copy this token and use it to authenticate your webhook request as needed.

With all the necessary values, you can send a REST API request to execute the remote command through Postman or other programs. The response of the API call will indicate the result of the command execution.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close