Triggering workflows

A quickstart on how to trigger workflows in Paragon.

All Paragon workflows start with a trigger, which determines when the workflow will run and how data gets passed into the workflow. There are two types of workflow triggers:

  • Scheduler - runs automatically at a scheduled time or interval

  • API Endpoint - runs when an HTTP request or webhook is sent to a trigger URL

In this section, we'll walk through common use cases for each trigger type and how you should use them.

Scheduler

The Scheduler trigger is used for workflows that need to run automatically at a scheduled time or interval. For example, you might want to query your database every week for users who match certain criteria to add to a re-engagement campaign, or send a daily user activity report on Slack.

The Scheduler trigger provides the following scheduling options:

  • Seconds (e.g. every 5 seconds)

  • Minutes (e.g. every 30 minutes)

  • Hourly (e.g. every hour at 15 minutes past the hour)

  • Daily (e.g. every 2 days at 9:00 am)

  • Weekly (every Monday at 12:00 pm)

To start running a scheduled workflow, click the Deploy button in the top-right of the screen to deploy the workflow. Once deployed, the workflow will begin to run automatically at the selected time.

API Endpoint

The API Endpoint trigger can be used to run workflows by sending it an HTTP request or webhook. This option also allows passing data from the incoming request into the workflow. For example, when a user uploads a document in your app, you could trigger a workflow that sends the document to an OCR API for processing before saving it to your database.

API Endpoint workflows can also be used as a way to create actual endpoints that extend functionality on top of your API. For example, if you need custom logic for an internal user operations tool (e.g. lookup user in a database, issue Stripe refund, send user email) you could build it in a Paragon workflow with an API Endpoint trigger that can be called from the frontend of the internal tool.

API Endpoint workflows can be triggered by sending an HTTP request to their unique URL. By default, the expected request type is set to POST, though this can be changed by clicking the dropdown menu next to the request type.

There are two ways to define what data you expect to be sent by incoming requests to the workflow:

  • Manually entering the expected request data

  • Automatically detecting data by sending a test request

Manually entering request data is usually the best option if you know what data will be sent by the incoming request (e.g. you're sending it from your own app). This option allows you to manually enter the expected query parameters (Params), headers (Headers), and body parameters (Body). Any data entered here can be used as variables by other steps in the workflow.

You can also choose to validate the incoming request data. For example, you can enforce that query parameters should be required, that headers should match an expected value, or that body parameters should match an expected type. If the incoming request doesn't meet your workflow's validation rules, the workflow will automatically return an error response.

Automatically detecting data from a test request is usually the best option if you don't know what data will be sent by the incoming request (e.g. you're receiving a webhook from another service). When you choose this option, the test shelf will appear and display a test URL at the bottom of the step sidebar. By sending a request to the test URL, Paragon will automatically detect data from the request and display it in the test shelf. Here, it'll be saved as test data that can be used as variables by other steps in the workflow.

Once you're ready to start using an API Endpoint workflow in production, click the "Deploy" button in the top-right of the screen to deploy the workflow. This will set the workflow's endpoint URL live and make it available for requests to be sent to.