Trigger Incident External Action‎

POST /Command/TriggerIncidentExternalAction

Trigger 'On Incident External Action' in the playbooks for the first incident that meets the search condition.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of your D3 SOAR account.
Site	`string`	Required	The D3 SOAR site to run the remote command.
Search Conditions	`JSON Object`	Required	The search condition is to find the first incident that occurred. The value query corresponding to the key supports regular expressions, string, number, { "$in": ["value1", "value2"] }, and, date:"$date": "2023-08-01T00:00:00Z" format.
Trigger Data	`JSON Object`	Required	'Trigger Data' is the data when 'On Incident External Action' is triggered in the incident playbooks.

READER NOTE

For Date/Time parameter Search Conditions, all times and timestamps must follow the ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ.

For example, May 15, 2024, 2:32 PM should be written as 2024-05-15T14:32:00Z.

Body Sample Data

application/json

CODE

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Search Conditions": {
      "Number": "20230413-123",
      "Type": "Suspicious Network Activity",
      "Status": "Open|Closed|In Progress|On Hold",
      "Stage": "Sample Stage",
      "DataSource": "QRadar Offense",
      "IncidentSource": "Sample Incident Source",
      "Connection": "QRadar Connection",
      "IngestionType": "Unknown|Schedule Job|Webhook|File|Command|Automation Rule|Manual Creation|Manual Escalation",
      "Category": "Incident Category",
      "ExternalKey": "Sample External Key",
      "CustomField1": "Sample Custom Field 1",
      "CustomField2": "Sample Custom Field 2",
      "Title": {
        "$regex": "^Incident Title"
      },
      "Severity": {
        "$in": [
          "Critical",
          "High"
        ]
      },
      "CreatedUtcTime": {
        "$gt": {
          "$date": "2023-09-01T00:00:00Z"
        },
        "$lt": {
          "$date": "2023-09-21T00:00:00Z"
        }
      }
    },
    "Trigger Data": {
      "CustomKey1": "Custom value1",
      "CustomKey2": "Custom value2"
    }
  }
}

Response

200 OK

application/json

Field Name	Type	Description
error	`string`	The error message if the API request has failed.
returnData	`JSON Object`	The return data from the API request.

CODE

{
    "error": "",
    "returnData": {
        "Status": "Successful",
        "Data": {
            "IncidentId": 123,
            "IncidentNo": "20230413-123",
            "TriggeredPlaybooks": [
                {
                    "RuntimeId": 287,
                    "PlaybookName": "Trigger External Action Playbook"
                }
            ]
        }
    }
}

401 Unauthorized

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

CODE

{"Error": "Invalid authentication key."}

429 TooManyRequests

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

CODE

{"Error": "The request exceeds rate limits or is otherwise blocked by rate limiting policies."}

500 InternalServerError

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

CODE

{"Error": "Unexpected Error."}