Custom HTTP Action

Custom HTTP Actions allow you to extend your pipeline functionality by utilizing APIs to perform GET, POST, PUT and DELETE http requests to external systems where you have REST API access.

There are multiple ways to use Custom HTTP Actions in your pipeline. For example, you can configure a custom action to validate an email address or phone number for a new lead using an external service.  

Prerequisites

• Understand the external system API that will be used with the Custom Action
• Access to the end system's REST API (Custom HTTP Actions only support REST APIs) 
• Pipeline Basics

Create a new Custom HTTP Action

In Syncari, navigate to Developer Studio and select the Custom Actions tab.

Click the Create New button then select the Create Action with HTTP. 

The next steps will provide instructions for working in the Custom HTTP Action editor.

Custom HTTP Action Setup

Configure the API Endpoint

1. Select the HTTP Method and enter the Endpoint URL

Configure the Authentication

1. Click the Authentication tab
2. Select the Authentication type
   • API Key - The API Key will be passed in both the header (header name, X-API-KEY) and url parameter (parameter name, api_key)
   • OAuth with Client Credentials - Will retrieve an OAuth token by using the Client Credentials Flow.
   • Bearer Token - This option will allow you to set an Authentication Bearer token as the authentication. Use this for a static bearer token.
   • Synapse Credentials - If you are using the API of a connected Synapse, you can utilize the same credentials for your custom action requests.
3. Credential - The modal for entering credentials will differ based on the authentication type selected. 
   • API Key type
     • Click New Credential
     • Enter a Name for the API Key
     • Enter the API Key value
   • OAuth with Client Credentials type
     • Click New Credential
     • Enter a Name for the Client Credentials
     • Enter the Client ID
     • Enter the Client Secret
     • Enter the Endpoint for retrieving an OAuth token
   • Bearer Token Credentials type
     • Click New Credential
     • Enter a Name
     • Enter the Bearer Token
   • Synapse Credentials
     • Select the Synapse from the list

Configure the request headers

Select the Headers tab to add any request header key/values that are required for the API request. Click Add to enter additional header key/values.

Configure the Variables

The Variables tab is where you to define the inputs for running your Custom Action. Variables can be referenced in the endpoint url, headers and body of the Custom Action configuration by setting the variable name in double curly brackets, {{variableName}}.

 Set the following properties when defining a variable:

• Name - This is the variable name that will be referenced when using the variable in the endpoint url, header or body of the custom action configuration.
• Display Name - This will display on the node configuration when using the custom action in your pipeline.
• Data Type - Set the data type for the variable. The available data types are boolean, date, datetime, double, integer, string, textarea, url and timestamp.
• Help Text - The help text will display when hovering over the variable when configuring the custom action node in your pipeline.
• Required - Set this to true or false.

Configure the Body (if required by the api request)

Enter the request body for the API request. The Body tab will only be visible when you select POST, PUT, DELETE and PATCH http methods. Using variables in the request body can be accomplished by using this format, {{variableName}} 

The request body can also be formatted by using the JTwig Template language. Reference JTwig Documentation.

Testing your configuration

Click the Proceed to Testing button to test the Custom HTTP Action. The testing step will allow you to test your configuration by sending an API request to the endpoint. You will have the ability to provide variable values when running the test.

1. Enter all necessary variable values
2. Click Run test Now

Running a test will allow you to inspect the request payload and response by clicking the Payload or Response tabs. 

Click Review Details to move on to the Review step.

Review

The review step will give you a summary of your custom action configuration. Review all the settings and click Next to finalize your Custom Action or click Previous to go back and re-configure any settings. 

1. Enter a Display Name 
2. The API name will be automatically set after the Display Name. You can customize the API name if needed. 
3. Enter Basic help text that will display when hovering a mouse pointer over the Custom Action help icon.
4. Set a Custom icon (optional)

Click Confirm & Save when done

Final Step: Publish the Draft

There is one final step before you can use the Custom Action in your pipelines.

The new custom action will appear on your Custom Actions list with a Draft status. Publish the draft of your Custom Action by clicking the kebab Menu icon on the Custom Action and select Publish.

What's next?

• Working with Custom Action Responses