Webhook Configuration Guide

LAST UPDATED: SEP 27, 2024

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:

Go to the Configuration section.
Navigate to Application Settings and select Web Config.
Locate the "EnableEnhanceWebhookAuthentication" configuration key.
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) 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.

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

g. (Optional) Check the Run MITRE TTP Search checkbox to enable the automatic mapping of ingested events from the data source to MITRE tactics and techniques.

h. (Optional) Check the Run Event Automation Rules checkbox 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) 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 Run MITRE TTP Search checkbox to enable the automatic mapping of ingested events from the data source to MITRE tactics and techniques.

j. (Optional) Check the Run Event Automation Rules checkbox 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)

Replace the sample value of the payload variable with the payload array copied from D3 SOAR.
Replace the sample value of the jwt_header variable with the header array copied from D3 SOAR.
Replace the sample value of secret_key variable with the secret key copied from D3 SOAR.
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. The mutable name of the remote command key. The modified key name can be observed upon re-entering the command page.

b. Request URL: The request URL for the HTTP request. When configuring an integration command, users will have access to a dropdown menu to select a site – once the site is selected, the Request URL will be automatically generated.

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.

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.

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 according to the sample to ensure 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. The input parameters vary for different commands. Therefore, users will need to construct the body data with the correct structure in their request.

WARNING
The request body data must be structured according to the sample to ensure 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)

Replace the sample value of the payload variable with the payload array copied from D3 SOAR.
Replace the sample value of the jwt_header variable with the header array copied from D3 SOAR.
Replace the sample value of secret_key variable with the secret key copied from D3 SOAR.
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.