Set Up an API Trigger

InsightConnect's API Trigger is used to trigger workflows from external applications via an HTTP POST. The API Trigger makes it easy to integrate and automate tools that offer webhook events by generating a custom endpoint URL for you. This also means you can easily trigger your workflow with a cURL or HTTP request.

In this article, we cover how to:

  1. Set up a new API Trigger
  2. Require API Key authentication
  3. Add API Trigger variables
  4. Trigger a Workflow with a cURL Command

Set up an API Trigger

To create a workflow with an API Trigger, follow these steps:

  1. Go to any Workflow page and click the blue Add Workflow button in the top right
  2. Select Start From Scratch.
  3. Enter a workflow name and optionally enter a description, tags, and time to complete manually.
  4. Select the API Trigger option from the Choose a Trigger menu.
  5. Enter a name and description for your trigger.
  6. If desired, check the Require API Key authentication box.
  7. Add the variables that will be included in your trigger events.
  8. Save the trigger configuration.
  9. Copy your Trigger URL.
  10. Direct webhooks, HTTP requests, and/or cURL commands to your Trigger URL!

Require API key authentication

By default, API triggers do not require authentication. The API endpoint associated with each API trigger provides security through obscurity by using unique, randomly generated UUIDs in each URL. Adding API key authentication provides an additional layer of security to prevent unwanted or potentially malicious events from triggering your workflow.

By checking the Require API Key authentication box in the trigger configuration menu, your trigger will require an X-API-Key authentication header in order to process incoming trigger events. The value for this field must be an active User or Organization API Key for your Insight account.

A note on requiring authentication

While many apps and services that support webhooks support adding custom headers, it is not a universal feature. As such, we recommend confirming your webhook source supports adding custom headers before selecting this option.

If you do choose to require the API key authentication for your API trigger, then use the following format for your cURL commands:

cURL
1
curl -X POST -H "X-Api-Key: <INSERT API KEY HERE>" -H "Content-Type: application/json" <INSERT API TRIGGER URL HERE> -d '{"taco":"bell", "burger":"king"}'

Add API Trigger variables

When setting up an API Trigger, you may define the variables that will be included in trigger event payloads. By doing so, it will be easier to build your workflow as you will be able to use these variables as step inputs using the + menu.

What if you don't know the variables?

No worries! The trigger will pass through any data that is sent in the post, so simply remove all the variables from your API trigger configuration and save it. Then, activate the workflow, fire the HTTP request (or wait for an event to occur in the source system), and find the resulting workflow Job in InsightConnect. The trigger output will show all the variables sent. You can even switch your view of the output to JSON to copy all the variables, reopen your trigger, and use the Enter JSON option to paste the JSON body in.

Trigger a workflow with a cURL command

To trigger a workflow with a cURL command, use the -d or --data flag in order to pass variables into your workflow. For example:

cURL
1
curl -X POST -H "X-Api-Key: <INSERT API KEY HERE>" -H "Content-Type: application/json" <INSERT API TRIGGER URL HERE> -d '{"taco":"bell", "burger":"king"}'