Automation

Playbook Connector for APIs

The playbook connector for APIs allows you to define custom HTTP requests to deliver your playbook data to any destination system that offers an API for integration. Here are some examples:

Alerting: Integrating a playbook with a simple notification API, like Slack or Twilio, can help you monitor when a playbook returns results and route those results to your Info-Sec team. You can route the data itself or just a text message indicating that results need to be reviewed.

Ticketing: Integrating a playbook with a ticketing system, like Jira or Zendesk, can transform playbook results into actionable information. The team that handles the ticket queue can have all the necessary data in the ticket, eliminating the need to log into the Bolster platform.

ETL pipelines: Integrating a playbook with an ETL pipeline can help you streamline analysis of trends. In this case, you might integrate the playbook with your internal API to load the necessary information into your data system. Your API could just save the results to a database or it could be the first ingestion step in a complex data pipeline that pulls data from various sources.

Supported Authentication Mechanisms

Any authentication mechanism that involves passing credentials or a token in HTTP headers/form data/request body will work. An authentication mechanism that requires a client to fetch credentials or time-based tokens from a grant workflow (such as Oauth 2.0) is not currently supported.

Before You Start

You will need some information about the endpoint you are calling for this integration. These include:

the URL of the endpoint you want to call
the type of HTTP request method
headers that endpoint expects
HTML form data
the body to be sent in the HTTP request

See the documentation for the API you are integrating with to determine the necessary values.

Step 1: Display the New Connector screen

Click the Automation tab.
Click Connectors.

3. Click New Connector.

Step 2: Display the API Connector screen

1. Enter a name for the connector.

This is the name that will display in the list of connectors.

2. Under Connector Type, select API from the dropdown list.

Step 3: Configure the API call

1. Use the following guidelines and the documentation for the target API to

Field Name	Field Description	Required
URL	URL of the endpoint that you are attempting to integrate with. When you schedule a playbook with this connector, this URL will be called when the playbook executes.	yes
Request Method	String representing any valid HTTP request method (GET, POST, PUT, etc.)	yes
Headers	Key-value pairs that will correspond with HTTP headers	no
Form Data	HTML form data	no
Request Body	The HTTP request body to be sent in the request. This can be free text, XML, JSON, or any format accepted by the API which you are attempting to call via a playbook.	no

2. (Optional) Add keywords to the fields if you want to substitute playbook information.

Keywords must be enclosed with %, as shown in the following table.

Keyword	Keyword Value
%FILE_NAME%	Name of the file which is created by the playbook.
%FILE_CONTENT%	Character array representing the actual contents of a playbook.
%FILE_URL%	URL of the file which contains your playbook data.

Here are some samples of keywords being used in an API connector:

Note: The format of the request body depends on the requirements of the target API.

Step 4: Test your connector

Once you have completed the API fields, click Test Connector.

If it worked:

You’ll see a Success! message.
You should see the expected action event on the target system.
If you used keywords in your API connector, the following values should be substituted for the keywords.

Keyword	Test Value
%FILE_NAME%	“test-file.txt”
%FILE_CONTENT%	“Success!”
%FILE_URL%	a URL which will download a file (test-file.txt). The file will contain the message “Success!”

If it didn’t work, you’ll see an error message containing: