This website uses Cookies. Click Accept to agree to our website's cookie use as described in our Privacy Policy. Click Preferences to customize your cookie settings.
Accept
Reject
Preferences
Log in to ask a question
Announcements
Check out the new Professional Security Operations Engineer certification beta!
Log in to ask a question

Security Operations: Execute ANY API request with HTTP V2 integration

‎02-27-2025 09:46 AM - edited ‎03-05-2025 10:45 AM

GCSCommunity
Staff
1 0 527

Author: Yuriy Landovsky

Introduction

At the end of 2024 we launched an HTTP V2 integration, which is designed to be a tool that you can use to integrate with ANY third party products without a need to write code. It's advanced and supports a comprehensive list of features including downloading files or Async workflows.

ylandovskyy_2-1738933507893.png

Authentication

HTTP V2 integration supports 3 types of authentication methods:

  • Basic Authentication Flow
  • API Key Flow
  • Dedicated Authentication Flow (Oauth)

It's important to emphasize that when you provide credentials as part of the integration configuration, they will not be exposed anywhere in the platform and you can safely use this integration, when you need to add more capabilities to your automation.

To ensure that no one will be able to do any tricks, when crafting payload, you should enable "Restrict Domain" parameter.

When it's enabled, the domain that is used inside integration configuration in "Test URL" will be enforced on all actions. For example, if you provided "https://www.virustotal.com" inside "Test URL", then in actions you will only be able to work with "www.virustotal.com". 

Basic Authentication Flow

Basic Authentication Flow is done via the following 3 integration parameters:

  • Test URL - represents the API request that you will use to test the connectivity to the third party API. Note: GET method is used to test connectivity, you can't change it to POST.
  • Basic Auth Username
  • Basic Auth Password

Example (ServiceNow)

ServiceNow API supports Basic Authentication. If we were to use HTTP V2 integration to authenticate to ServiceNow, then your configuration would be like this:

Test URL  https://{your_instance.com}/api/now/table/incident/{incident_id}
Basic Auth Username {Username}
Basic Auth Password {Password}

If everything is configured correctly, then you expect to see the green checkmark.

ylandovskyy_3-1738934448950.png

If you don't see a green checkmark, pay attention to the error message. Considering that we are executing the raw API request, the error will come from the third party API.

API Key Flow

API Key Flow is done via the following 3 integration parameters:

  • Test URL
  • API Key Field Name - defines the name of the header that should be used for authentication.
  • API Key Secret - defines the secret that should be assigned to the header.

The idea here is to support products that provide authentication as part of the header. For example, VirusTotal expects you to provide x-apikey for authentication.

Example (Google SecOps SOAR API)
In order to authenticate to SOAR API, you need to provide the following API key as part of the AppKey header. So, our configuration will look like:

Test URL https://{SOAR_API Root}/api/external/v1/idp-group-mapping
API Key Field Name AppKey
API Key Secret {SOAR API Key}

ylandovskyy_4-1738935047004.png

Dedicated Authentication Flow (OAuth)

Dedicated Authentication Flow is designed to support workflows, where the authentication is done in 2 parts: first an access token is generated and then the access token is used for authentication to the API requests.
This flow requires the following integration parameters:

  • Dedicated Auth API Request Method
  • Dedicated Auth API Request URL
  • Dedicated Auth API Request Headers
  • Dedicated Auth API Request Body
  • Dedicated Auth API Request Token Field Name

Note: Test URL is not used during dedicated auth flow, except for the "Restrict Domain" use case.
This authentication is a little bit more sophisticated, so let's get into details.

Dedicated Auth API Request Method parameter dictates what API Request Method is needed to generate the access token (for example, POST).

Dedicated Auth API Request URL parameter dictates what API Request needs to be executed to generate the access token (for example, in Crowdstrike, the request will be https://api.crowdstrike.com/oauth2/token).

Dedicated Auth API Request Headers parameter dictates the headers that are needed for the successful generation of access token. Headers are provided as a JSON object. For example, if you need to provide “Content-type”: “application/x-www-form-urlencoded” Header, then the input for the parameter will look like this:

 

{ 
"Content-type": "application/x-www-form-urlencoded" 
}

 

Dedicated Auth API Request Body parameter dictates the payload for the API request. The payload is provided in the format of a JSON object.

Dedicated Auth API Request Token Field Name parameter dictates the name of the key, where the generated access token is stored from response. Later in the actions, you will reference it as {{integration.token}} and the integration will know, where to put the generated access token.

Example (Crowdstrike API)
In order to authenticate to Crowdstrike, you need to build the following HTTP Request:

 

POST /oauth2/token HTTP/1.1
Host: api.crowdstrike.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 97

client_id={client id}&client_secret={client secret}

 

If we were to translate this HTTP request into the integration configuration, you would need to provide the following:

Dedicated Auth API Request Method POST
Dedicated Auth API Request URL https://api.crowdstrike.com/oauth2/token
Dedicated Auth API Request Headers 
{
   "Content-type": "application/x-www-form-urlencoded"
}
Dedicated Auth API Request Body 
{
   "client_id": "{client id}",
   "client_secret": "{client secret}"
}

As mentioned before,  Dedicated Auth API Request Headers and Dedicated Auth API Request Body always expect a JSON object to be provided, but depending on the "Content-type" header, the integration will adjust the payload into the correct format. In this case:

 

{
   "client_id": "{client id}",
   "client_secret": "{client secret}"
}

 

 will be translated into POST parameter payload

 

client_id={client id}&client_secret={client secret}

 

The next step is to provide the integration information about, where the generated token will be stored. Successful response for the API request to generate token looks like this in Crowdstrike:

 

{
   "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCIO4…",
   "expires_in": 1799,
   "token_type": "bearer"
}

 

As we can see, the necessary token is stored in the "access_token" key, which means that we need to provide inside the integration configuration:

Dedicated Auth API Request Token Field Name access_token

Note: If in the response the access_token is located in the nested JSON like this:

 

{
   "data": {
       "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCIZMI3DQAQsYibMpO4…",
       "expires_in": 1799,
       "token_type": "bearer"
   }
}

 

Then in the Dedicated Auth API Request Token Field Name parameter, you will need to provide "data_access_token” instead of just “access_token”.

Anytime you are using "Execute HTTP Request" action, the integration in the background will generate a new token and use it for authentication. To use this new token, integration has a dedicated placeholder in the format of “{{integration.token}}”. Whenever this placeholder is provided in the payload, it will store the generated token.

Let's assume that we want to execute the following API request:

 

POST /falconx/entities/submissions/v1 HTTP/1.1
Host: api.crowdstrike.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzphNDdiNTc2MS…
Content-Length: 209


{
   "sandbox": [{
       "sha256": "9854c9dfded29d8442499daba01082ba5d164aa02e44a6f4c59d38677dda97e3",
       "environment_id": 100,
       "submit_name": "filename.pdf"
   }]
}

 

Crowdstrike expects that the "access_token" will be provided as part of "Authorization" header. This means that when you will be providing the headers for the API request inside "Execute HTTP Request" action, you will need to provide 1 line in the JSON object that will look like this:

 

{
    "Authorization": "Bearer {{integration.token}}"
}

 

Now, the setup is completed and we can successfully execute Crowdstrike API requests.

ylandovskyy_0-1738938792616.png

CA Certificate

If a Remote Agent is used to connect to the on-prem product, then you might want an additional layer of security by supplying the integration with CA Certificate. CA Certificate is used to ensure the integrity of the connection. 

The parameter expects a Base64 encoded certificate file. All of the API requests will use this certificate once it’s supplied.

How to use “Execute HTTP Request” action

The purpose of this action is to craft a custom HTTP request and get information as JSON Result. You can modify all of the components that are used to build the HTTP request.

URL Params, Headers, Cookie Parameters

All of the parameters here leverage the JSON object format as input.
For example, if URL Params parameter has value:

 

{
   "parameter": "value",
   "sorting": "asc"
}

 

Then this will be transformed in the backend to: 

 

?parameter=value&sorting=asc

 

If the Headers parameter has value:

 

{
   "Accept": "application/json",
   "User-Agent": "Google Secops"
}

 

Then in the HTTP request you will have:

 

Accept: application/json
User-Agent: Google Secops

 

If the Cookie parameter has value:

 

{
   "PHPSESSID": "298zf09hf012fh2",
   "csrftoken": "u32t4o3tb3gg43"
}

 

Then in the HTTP request you will have a header called “Cookie” with value:

 

Cookie: PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43;

 

Body Payload Parameter

The body payload is also provided as a JSON object for all of the situations, except, if it’s an XML or “multipart/form-data” content.

To ensure that the body is constructed correctly, it’s important to make sure that the correct “Content-type” header is provided in the “Headers” parameter, because depending on the value, the action will construct a different payload.

Let’s assume that your input in the “Body Payload” is this:

 

{
   "Id": "yuriy",
   "sorting": "asc"
}

 

If the "Content-type” is “application/x-www-form-urlencoded” then the action will generate this payload:

 

Id=yuriy&sorting=asc

 

If the “Content-type” is “application/json” then the action will generate this payload:

 

{
   "Id": "yuriy",
   "sorting": "asc"
}

 

If you are working with XML, then you need to make sure that “Content-type” header has “text/xml” as value. In this scenario, the expected payload is a proper XML input like in the example below:

 

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
     <ubiNum>500</ubiNum>
   </NumberToWords>
 </soap:Body>
</soap:Envelope>

 

If you are submitting/uploading a file via API request, you will need to provide the base64 encoded version of the file in the “Body Payload” parameter and ensure that the header “Content-type”: “multipart/form-data” is set. Here is an example of the payload (image in this case):

 

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

 

Working in ASYNC flow

Certain API workflows require waiting for the response to finish processing, before the next API request can be executed.

For example, in SIEM products it’s common to create a search Job, where you need to wait for the search Job to finish execution and only then fetch results. This use case is solvable with HTTP V2 integration via the “Expected Response Values” parameter.

As an example let’s assume that some API returned this response:

 

{
   "state": "in_progress",
   "percentage": "10"
}

 

“state” field can have the following values:

  • error
  • in_progress
  • finished

"percentage" field can return values in range from 1 to 100.

If you will provide in parameter “Expected Response Values”:

 

{
   "state": "finished"
}

 

Then the action will work in ASYNC mode and wait until in the response we will have "state": "finished”

If you will provide:

 

{
   "state": [
       "finished",
       "error"
   ]
}

 

Then the action will work in ASYNC mode and wait until in the response we will have "state": "finished” OR "state": "error”.

If you will provide:

 

{
   "state": "finished",
   "percentage": "100"
}

 

Then the action will work in ASYNC mode and wait until in the response we will have "state": "finished” AND "percentage": "100”.

You can also provide even more complex conditions like this:

 

{
   "state": [
       "finished",
       "error"
   ],
   "percentage": "100"
}

 

For this setup, action will wait for “state” to be either “finished” OR “error” AND “percentage” to be “100”.

Note: when action searches for the key, it will search it in the whole JSON object and perform a match with the first value.

 

{
   "data": {
       "state": [
           "finished",
           "error"
       ],
       "percentage": "100"
   }
}

 

You don’t need to provide “data_state” or “data.state”, it’s still just “state”.

Working with files

When talking about file workflows, it’s important to highlight 2 separated flows:

  • Downloading the file
  • Uploading the file

Currently, to upload the file you need to prepare it in Base64 format and then submit it as part of “Body Payload”.

When talking about downloading workflows:

  • To return the data as part of JSON result in Base64 format, you need to enable the “Base64 Output” parameter. 
  • If you want to save the file to the case wall, then you need to enable the “Save To Case Wall” parameter. Note: all files are downloaded as zips.

Additionally, if you are working with sensitive files like malware, then it’s recommended to enable the “Password Protect Zip” parameter. The password that will be set for all of the password protected zips is “infected”.

Blocks-As-Code

You can use HTTP V2 integration and Playbook Block infrastructure to build reusable content. For example, you can create a block that will contain a HTTPV2 action and then configure all of the inputs to be take from the block inputs, like this:

ylandovskyy_2-1738943302069.png

In this example, we created 3 input parameters for the block:

  • comment
  • sys_id
  • table_name

Later block inputs are used as placeholders for the action as seen in the second screenshot below:

ylandovskyy_4-1738943438637.png

Widgets

This integration supports Predefined Widgets. The widgets work with the "response_data" key. Depending on the response, whether it's a list of JSON objects or it's just a JSON object, the widget will adapt and render data differently.

ylandovskyy_0-1738944181417.png

ylandovskyy_1-1738944227413.png

Conclusion


The HTTP V2 integration is a powerful, versatile tool that allows users to integrate with any third party product without writing code. The integration supports a wide range of features, including downloading files and Async workflows. With its advanced authentication methods, the HTTP V2 integration provides users with a safe and efficient way to connect with third party products.

Contributors
Version history
Last update:
‎03-05-2025 10:45 AM
Updated by: