The Playbook API connector allows you to define custom HTTP requests which will deliver your playbook data to any destination system of your choice. This document is an overview of the potential use cases and a walkthrough of how to use the playbooks API connector.
Use cases
The playbooks API connector can be used for a wide range of integrations. The use cases below aren't comprehensive by any means but they do represent some popular implementations.
Alerting
Playbooks only trigger when the specified query has at-least one result. A playbook integrated with a simple notification API (slack, twilio, etc) can be used as a way of monitoring when a certain playbook query returns results. Let's assume we setup a playbook with a daily query to find new phishing sites which have emerged in the last day. This playbook can use an API connector which sends a message to your info-sec team via Twilio. This message need not even include the playbook data, it can simply be an alert which lets your team know that some additional action is required. They can login in platform.bolser.ai and investigate further.
Ticketing
You may want to track a certain playbooks results with more rigor than a simple alert. Let's say you want to create a ticket when a playbook has results in order to ensure a certain team follows up. The API connector can be used to integrate with ticketing platforms such as JIRA, Zendesk, and others to create a ticket with the desired playbook attributes as the contents of that ticket. The team that handles that ticket queue can have all the desired data on the ticket itself and may not even need access to platform.bolster.ai
ETL pipelines
Some use cases are more complex than getting an alert, creating a ticket or even just manually viewing the output data. Perhaps you want to run aggregations on the output of a certain playbook to better understand trends. In this case you may want to setup your own API which will transform the playbook data to your needs and load it into your data systems. Your API could be as simple as saving the results to a database or could be the first ingestion step into a complex data pipeline which pulls data from various sources.
Overview
Supported Fields
The API connector supports the following fields:
| Field Name | Field Description | Required |
|---|---|---|
| Connector Name | The name assigned to your API connector. When you create/edit a Playbook and select the associated connector, this name will show in the dropdown | yes |
| Connector Type | The connector type dropdown will include multiple options. In order to setup an API connector, select the “API” option. | yes |
| URL | URL of the endpoint which 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 which 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 |
Keyword Substitution
The API connector has certain reserved keywords. You specify these keywords in the request body, form data, URL or header fields when creating your custom API connector. When the playbook is run with your newly created connector, these keywords will be substituted with their relevant values. Keywords must wrapped in a leading and trailing % as shown below in the 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:
These are just examples of keywords in use based on the format that certain API’s accept. Your format may be totally different and you may use only one (or more) keyword(s) depending on your use case. You may not even need to use any keywords (i.e you are setting a notification mechanism just to receive an alert when your playbook has any results).
Testing your Connector
Once you have all the details for your custom API connector filled out, its time to make sure the connector is working as configured. This can be easily done with the “Test Connector” button located on the API connector modal.
When you click “Test Connector”, Playbooks will send the request as configured to the specified URL. If a success HTTP code is returned, you will see a “Success!” message. You should also see the expected action/event on the system you are attempting to integrate with. If you used keywords in your API connector, these values should be substituted for the keywords.
| Keyword | Test Value |
|---|---|
| %FILE_NAME% | “test-file.txt” |
| %FILE_CONTENT% | “Success!” |
| %FILE_URL% | an URL which will download a file (test-file.txt). The file will contain the message “Success!” |
If a failure HTTP code is returned to Playbooks, you will see an error message. This error message will contain the failure HTTP code and the error message returned by the API you are attempting to configure (if any).
Examples
Zoom Chat
Zoom offers a webhook based chat app which can be added to chat rooms. We will explore how to leverage the API connector in order to publish our playbook results to Zoom chat.
Perquisites: a zoom account. A free account will suffice for the purposes of this demo
Step 1: Create a webhook-only zoom app by following this guide https://zoomappdocs.docs.stoplight.io/incoming-webhook-chatbot. Take note of your generated webhook url and the authorization token
Step 2: Create a playbook API connector in the following format. Use the “test connector” functionality to ensure a successful integration. You should see a “test-file.txt” delivered to your zoom chat client (in whatever channel you added the incoming webhook app).
Step 3: Create a playbook and use your newly created API connector. Once the playbook is saved, use the “run now” functionality and you should see the contents of the playbook in your zoom chat client!
FAQ
What types of authentication are supported by the API connector?
Any authentication mechanism that involves passing credentials or a token in HTTP headers/form data/request body will work. An authentication mechanism which requires a client to fetch credentials or time-based tokens from a grant workflow (such as Oauth 2.0) is not currently supported.