Using Workflow HTTP Steps
Let’s say you have a workflow that crunches some data, and produces some awesome output. Now you want to send this output to an external service by making an API call. Or, you just want to send a slack message with the result of the previous step? How do you achieve this?
Workflows have just the perfect solution for this - HTTP Step. The HTTP Step allows you to make an HTTP API call with any Authentication mechanism and payload. The best part - you can use the outputs of parent steps to create an awesome, dynamic payload.
Before we look into the examples, let’s see how we can create an HTTP step and the different parameters that it supports.
HTTP Step
As mentioned above, the HTTP step allows you to make an API call to the provided URL with a given payload and headers. So, to create an HTTP step, you need to define the following parameters:
method: The HTTP method to use when making the API call.Allowed values are -
get,post,put,patch, anddelete
url: The URL to make the API call to.payload: The stringified payload to be passed when making a non-GET request.The payload can be a static value or it can be parameterised as well.
{{}}syntax can be used to add value from input parameters in the payload.Let’s say, you have an input parameter called
dataand a custom-type secret calledsecret. To use these as values in the payload, you can use the following syntax{ "data": "{{data}}", "secret": "{{SECRET_CUSTOM}}", "static": "value" }
But that’s not all, you can parameterise the whole payload as well by using the following syntax
"{{payload}}"In this case, the
payloadis taken from an input parameter calledpayloadwhich should be a valid JSON.
auth: The authentication method to be used while making the API call. This is an object with following valuestype: The type of authentication to be used.Allowed values are -
no-auth,oauth,basic,api-key, andbearer-token.
Each authentication type has different set of required parameters
no-auth: Select this if you want to hit the API without any Authorization header.oauth: In this case the access token is fetched first using the given parameters, and then this access token is passed in theAuthorizationheader. We only supportclient credentialsgrant type.clientId: The client ID to be used to get the access token. The value should be the name of the external credential containing the client ID.clientSecret: The client secret to be used to get the access token. The value should be the name of the external credential containing the client secret.authUrl: The URL that is hit to get the access token.
basic: This takes theusernameandpasswordwhich arebase64-encoded to get the value for the authorization header. Required parameters areusernamepassword
api-key: This calls the API with the given API Key. Required parameterapiKey: The name of the external credential that contains the API key.
bearer-token: This calls the API with the given bearer token. Don’t prependBearerto the token, the step handles that for you.bearerToken: The name of the external credential that contains the bearer token.
headers: The headers to be passed when making the API call. This is an object with following two valuesabsolute: An object with the key representing the name of the header and value representing the static value for the header.secrets: An object with the key representing the name of the header and value representing the name of the external credential which contains the value of the header.Any sensitive data should be passed as a secret only.
Here’s an example workflow config for a workflow with a single HTTP step
body:
name: http-workflow
triggers: []
watchers: []
tags: []
steps:
step-1:
type: http # The step type, it should be http for HTTP step
method: get # The HTTP method to use for making the API call
url: https://peak.ai # The URL to make the call to
auth:
type: oauth # The authentication type
# Parameters needed for the given authentication type
clientId: client-id
clientSecret: client-secret
authUrl: https://get-access-token
payload: "{}" # The stringified payload that should be passed while making the API call
headers:
absolute:
x-auth-tenant: some-tenant # Headers with absolute value
secrets:
x-auth-token: token # Headers that take value from external credentials
Now let’s checkout some real-world examples to see how the step can be used.
Examples
Send output in an Email
Let’s say, we have a workflow with a standard step that does some processing and produces some output. We now want to send this output as an email to our customers. We can use the HTTP step combined with the send email API to achieve this. Here’s a sample workflow config that can help in achieving this
---
body:
name: process-data
triggers: []
watchers: []
tags: []
steps:
process-data: # Standard step that produces the required output
type: standard
imageId: 1
imageVersionId: 1
command: "python script.py" # The script.py script runs and adds the output to output.txt
resources:
instanceTypeId: 21
storage: 10GB
parents: []
outputParameters:
result: "output.txt" # Expose the output from output.txt as output parameter named "result"
send-email: # HTTP step to send email
type: http
method: post # Make a POST request to the given URL
url: https://service.peak.ai/notifications/api/v1/emails # The URL to make the API call to
payload: |
{
"recipients": ["{{email}}"],
"cc": [],
"bcc": [],
"subject": "Here's your output",
"templateName": "awesome_template",
"templateParameters": {
"output": "{{result}}"
}
}
auth:
type: api-key # Use API Key authentication
apiKey: tenant-api-key # The value of the tenant-api-key secret would be passed in the authorization header
headers:
absolute:
"Content-Type": "application/json" # Pass the Content-Type header with application/json value
parameters:
env:
email: "user@peak.ai"
inherit:
result: result # Inherit the result output parameter from the process-data step as input parameter
In the above example, process-data step outputs the data in an output parameter called result. The result output parameter is then added as a parameter in the send-email step which uses it in the payload to pass in the templateParameters.
Ingest data from external API
Let’s say, we have a workflow with in which we first want to fetch some data from an external API, then process it, and finally store it in some table. HTTP step can help with this as well. Here’s what we can do
Create an HTTP step that hits the API. HTTP steps stores the API response in a file called
response.txt. This is already available as output to be consumed via output parametersThe output parameter from the HTTP step can be used in a standard step to get the data and perform processing.
Here’s a sample implementation for the same
--- body: name: process-data triggers: [] watchers: [] tags: [] steps: get-data: # HTTP step that fetches data from the given API type: http method: get # Make a GET request to the given URL url: https://external-service.com/get-data auth: type: oauth # Use OAuth authentication clientId: tenant-client-id clientSecret: tenant-client-secret # The given URL will be hit to get the access token first, which would then be passed in Authorization header authUrl: https://external-service.com/get-access-token headers: absolute: "Content-Type": "application/json" outputParameters: result: response.txt # Add the API response in an output parameter called result process-data: # Standard Step that processes the ingested data type: standard imageId: 1 imageVersionId: 1 command: "python script.py" resources: instanceTypeId: 21 storage: 10GB parents: ["get-data"] parameters: inherit: result: result # Inherit the API response from the get-data step in an input parameter called result
In the above example, process-data step outputs the data in an output parameter called result. The result output parameter is then added as a parameter in the send-email step which uses it in the payload to pass in the templateParameters.