Utility Command API: Get Events | Get Incidents

LAST UPDATED: APRIL 7, 2025

The D3 utility command API enables the execution of configured utility commands via REST API by sending requests to D3. This article outlines how to configure the necessary webhook settings to use the Get Events and Get Incidents utility commands remotely, each provided with a use case example.

Webhook Setup

Navigate to Configuration > Utility Commands > Get Events / Get Incidents.
Click the toggle next to the Webhook Authentication header to allow the command to be run remotely (e.g., via Postman).
Click the API Key button.
Generate an API key.
1. Click the + button.
2. Enter a name for the key.
3. Click the Generate button.
The generated key will be displayed in an accordion along with information required to make an API request.

READER NOTE

When constructing the API request, users are advised to copy the sample request body and modify it accordingly. This approach helps maintain the integrity of the request data's structure and format. Refer to API Key Authentication for more information on making a request using a platform such as Postman.

Get Events

The Get Events utility command can be used remotely via REST API. A filtered list of ingested events from D3 SOAR will be returned based on the criteria specified in the request body fields.

Request Body Fields for Sending API Requests from External Applications

Get Events Request Body Fields

Request Body Fields	Description
Username	The username of the D3 SOAR user account making the request.
Site	The D3 SOAR site containing the desired events to retrieve with the request.
Command Params	An object containing the parameters required for executing the command.
Filter	The array of criteria, each containing one or more JSON object conditions, used to filter events. The "field" key points to an event field. The "operator" key is the condition operator that establishes the logical relationship between the field and the value. The supported operators are: ["<", ">", "=", "<=", ">=", "!=", "LIKE", "IS EMPTY", and "IS NOT EMPTY"]. The "value" key is the data or criterion that the field is compared against. The "AND" logic applies between JSON objects within the same array, whereas the "OR" logic applies between different arrays.
Fields	The event fields to include in the response data. If no fields are specified, the default fields displayed are all those listed in the Sample Data, except for "Event Raw Data."
Start Time	The start time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the input format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00).
End Time	The end time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the DateTime format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00).
Output Format	Allows users to choose the format in which to present event data. Available options are: CSV (1) JSON (2) CSV link (3) JSON link (4)
Page Index	The page number to view a subset of events. For example, if there exists 50 events, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one event will be displayed. The default page index is 0, indicating the first page. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the provide page index is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Page Size	The maximum number of event records to fetch, ranging from 1 to 1000. For example, if there exists 50 events, and the Page Size is set to 49, and the Page Index (the previous parameter) is set to 1 (the second page), only one event will be displayed. If no value or 0 is provided, a default page size of 100 will be applied. If no value or 0 is provided for both Page Index and Page Size, all events will be fetched. If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Sort Field	The field by which the results are sorted. Users can specify any field listed in the Fields parameter (e.g., `Date Created`, `Event ID`, etc.). Sorting will not apply to fields excluded from the Fields parameter. Fields containing a period (.) in their name are not supported for sorting.
Sort Order	The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour.

Example Use Case

Refer to the following example use case to structure an API request body for the Get Events command.

EXAMPLE The objective is to use the command via webhook to retrieve events from D3. Consider the following criteria:

Events are ingested from SentinelOne, with a status of "Open," or
Events are ingested from SentinelOne with a status of "Escalated".

Criterion 1 Array

The first array, aligned with criterion 1, is as follows:

JSON

[
   {
      "field":"Data Source",
      "operator":"=",
      "value":"SentinelOne"
   },
   {
      "field":"Status",
      "operator":"=",
      "value":"Open"
   }
]

Criterion 2 Array

The second array, aligned with criterion 2, is as follows:

JSON

[
    {
        "field": "Data Source",
        "operator": "=",
        "value": "SentinelOne"
    },
    {
        "field": "Status",
        "operator": "=",
        "value": "Escalated"
    }
]

READER NOTE

For the Get Events utility command, variations in the Fields command parameter exist across different vSOC versions. Consult the official utility command documentation to identify the fields available in the output.

Constructing the Sample Request Body

By combining the two filter arrays with the required request body fields for vSOC version 16.8 and above, the complete request body may resemble the following. Adjust the Username and Site fields to reflect the user executing the command and the site where the events are ingested.

Sample Request Body

JSON

{
   "Username":"Admin",
   "Site":"Security Operations",
   "CommandParams":{
      "Filter":[
         [
            {
               "field":"Data Source",
               "operator":"=",
               "value":"SentinelOne"
            },
            {
               "field":"Status",
               "operator":"=",
               "value":"Open"
            }
         ],
         [
            {
               "field":"Data Source",
               "operator":"=",
               "value":"SentinelOne"
            },
            {
               "field":"Status",
               "operator":"=",
               "value":"Escalated"
            }
         ]
      ],
      "Fields":[
         "Event ID",
         "Site",
         "Tactic",
         "Technique",
         "Description",
         "Time of Occurrence (UTC)",
         "Intake Time (UTC)",
         "Status",
         "Data Source"
      ],
      "Start Time":"2025-01-01 00:00:00",
      "End Time":"2025-04-03 00:00:00",
      "Output Format":2,
      "Page Index":0,
      "Page Size":2,
      "Sort Field": "Event ID",
      "Sort Order": "Descending"
   }
}

Making the Request via Postman

Once the sample request body is constructed, users can proceed to Postman or another API testing platform to execute the command remotely.

Copy the request URL in vSOC.
In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.
In vSOC, copy the request header key.
In Postman, click on the Headers tab, then paste the request header key under the Key column.
In vSOC, copy the request header value.
In Postman, paste the request header value under the Value column.
Select the Body tab, choose the raw option, then paste the sample request body data constructed in Constructing the Sample Request Body.
Click the Send button to send the request.

RESULT

A successful call with event data will have the 200 OK message and return data similar to the following:

Get Incidents

The Get Incidents utility command can be used remotely via REST API. A filtered list of ingested incidents from D3 SOAR will be returned based on the criteria specified in the request body fields.

Request Body Fields for Send API Requests from External Applications

Get Incidents Request Body Fields

Request Body Fields	Description
Username	The username of the D3 SOAR user account making the request.
Site	The D3 SOAR site containing the desired incidents to retrieve with the request.
Command Params	An object containing the parameters required for executing the command.
Filter	The list of criteria, each containing one or more JSON object conditions, used to filter incidents. The "field" key points to an incident field. The "operator" key is the condition operator that establishes the logical relationship between the field and the value. The supported operators are: ["<", ">", "=", "<=", ">=", "!=", "LIKE", "IS EMPTY", and "IS NOT EMPTY"]. The "value" key is the data or criterion that the field is compared against. The "section" key is optional. When included in a condition, filtering will use Dynamic Fields instead of Static Fields. The "field" property must be assigned a value that matches the name of an Activity or Info Activity UI block under the specified section in the Incident Form Editor. The "AND" logic applies between JSON objects within the same array, whereas the "OR" logic applies between different arrays. For non-dynamic "field" values, refer to the sample data for the following Static Fields input parameter.
Static Fields	The static incident fields to be included in the results. Default fields will be selected for each resulting incident if the Static Fields input is left empty. For D3 vSOC versions earlier than 16.8, default fields are all those in the sample data except for "Incident Raw Data" and "Event Raw Data." For D3 vSOC versions 16.8 and later, default fields are all those in the sample data except for "Date Closed," "Closed by," "Incident Raw Data" and "Custom Field." In these later versions, the "Playbook" static field returns playbooks that have either been completed or stopped due to an error. The static fields "Date Created," "Date Modified" and "Date Closed" are in UTC time.
Dynamic Fields	The dynamic incident fields to be included in the results. A key in the JSON object is the user-specified Section name of a dynamic field (i.e. incident form). The value (string array) corresponding to a key is the user-specified Activity or Info Activity name within the section.
Start Time	The start time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
End Time	The end time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
Output Format	Allows users to choose the format in which to present incident data. Available options are: CSV (1) JSON (2) CSV link (3) JSON link (4)
Page Index	A page of incident records. The default page index is 0, indicating the first page. For example, if there exists 50 incidents, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one incident will be displayed. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the provide page index is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Page Size	The number of incident records to display within a page, ranging from 1 to 1000. If no value or 0 is provided, a default page size of 100 will be applied. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Sort Field	The name of the static or dynamic field by which to sort the results. Formatting requirements are as follows: Static fields: Use the field name directly (e.g., `Date Created`). Dynamic fields: Combine the section and field name (e.g., Customer.Name). If the field name contains quotes or spaces, enclose it in quotes and escape any inner quotes (e.g., `Customer "Name".Last "Name"` should be reformatted as `"Customer /"Name/""."Last /"Name/""`). Incident custom fields: Must begin with `Custom` (case-sensitive), such as `Custom Sample`. Sorting is only supported if the field is included in the Static Fields or Dynamic Fields parameter. Nested dynamic fields beyond one level are not supported. Fields containing a period (.) in their name are not supported (except for Incident No.).
Sort Order	The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour.

Example Use Case

Refer to the following example use case to structure an API request body for the Get Incidents command.

EXAMPLE The objective is to use the command via webhook to retrieve incidents from D3. Consider the following incident criteria:

The status is "Open," the severity level is "Critical," and the incident owner is "Admin User." or
The status is "Open," the severity level is "High," and the incident owner is "Admin User.”

Criterion 1 Array

The first array, aligned with criterion 1, is as follows:

JSON

[
   {
      "field":"Status",
      "operator":"=",
      "value":"Open"
   },
   {
      "field":"Severity",
      "operator":"=",
      "value":"Critical"
   },
   {
      "field":"Owner",
      "operator":"=",
      "value":"Admin User"
   }
]

Criterion 2 Array

The second array, aligned with criterion 2, is as follows:

JSON

[
   {
      "field":"Status",
      "operator":"=",
      "value":"Open"
   },
   {
      "field":"Severity",
      "operator":"=",
      "value":"High"
   },
   {
      "field":"Owner",
      "operator":"=",
      "value":"Admin User"
   }
]

READER NOTE

For the Get Incidents utility command, variations in the Static Fields command parameter exist across different vSOC versions. Consult the official utility command documentation to identify the static fields available in the output.

Constructing the Sample Request Body

By combining the two filter arrays with the required request body fields for vSOC version 16.8 and above, the complete request body may resemble the following. Adjust the Username and Site fields to reflect the user executing the command and the site where the incidents are located.

Sample Request Body

JSON

{
    "Username": "Admin",
    "Site": "Security Operations",
    "CommandParams": {
        "Filter": [
            [
                {
                    "field": "Status",
                    "operator": "=",
                    "value": "Open"
                },
                {
                    "field": "Severity",
                    "operator": "=",
                    "value": "Critical"
                },
                {
                    "field": "Owner",
                    "operator": "=",
                    "value": "Admin User"
                }
            ],
            [
                {
                    "field": "Status",
                    "operator": "=",
                    "value": "Open"
                },
                {
                    "field": "Severity",
                    "operator": "=",
                    "value": "High"
                },
                {
                    "field": "Owner",
                    "operator": "=",
                    "value": "Admin User"
                }
            ]
        ],
        "Static Fields": [
            "Incident No.",
            "Incident Type",
            "Title",
            "Status",
            "Severity",
            "Stage",
            "Owner",
            "Date Created (UTC)"
        ],
        "Dynamic Fields": {
            "Blacklist Check": [
                "IPs in the Blacklist",
                "Domains in the Blacklist",
                "Host Name in the Blacklist"
            ],
            "Whitelist Check": [
                "IPs in the Whitelist",
                "Domains in the Whitelist",
                "Host Name in the Whitelist"
            ]
        },
        "Start Time": "2025-02-06 21:31:00",
        "End Time": "2025-04-06 23:30:00",
        "Output Format": 2,
        "Page Index": 0,
        "Page Size": 100,
        "Sort Field": "Incident No.",
        "Sort Order": "Ascending"
    }
}

Making the Request via Postman

Once the sample request body is constructed, users can proceed to Postman or another API testing platform to execute the command remotely.

Copy the request URL in vSOC.
In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.
In vSOC, copy the request header key.
In Postman, click on the Headers tab, then paste the request header key under the Key column.
In vSOC, copy the request header value.
In Postman, paste the request header value under the Value column.
Select the Body tab, choose the raw option, then paste the sample request body data constructed in Constructing the Sample Request Body.
Click the Send button to send the request.

RESULT

A successful call with incident data will have the 200 OK message and return data similar to the following: