Sending a Response

Workflows triggered by API request can send a custom response.

Overview

Paragon workflows can be used to create actual API Endpoints that extend functionality on top of your own API or database. In these use cases, the Response step allows you to send data back to the service (e.g. your web app or API) that sent the initial request to trigger your workflow.

For example, you might have an app where users upload documents that you want to process using OCR. You could use a Paragon workflow to create an endpoint that gets called by your app when a document is uploaded. The workflow could then send the document to an OCR API, save the results to your database, and send a response back to your app so it can display the processed document text in your app's UI.

To add a response to your workflow, click the "+" button in the workflow canvas and choose the Response step in the sidebar. You can only add a response to workflows with an API Endpoint trigger.

Defining response data

There are two components to a Response: its status code and its data.

In general, you should send the 200: OK status code if the workflow ran successfully, you can choose from other commonly used status codes for more specific cases (e.g. if a Request failed, send an error response).

You can choose what data to send the response body using the key-value table to reference data from previous steps in the workflow.

Sending files in responses

You can use the Response step to send files to your application. To do so, select "File" as the Response Type and reference a File object from a previous step.

File objects are returned from file-related Integration Actions and Request steps which include a file in the response.

A File Response will be returned to the original HTTP request with the Content-Type of the file's MIME type and the raw bytes of the underlying file.

Response time limitations

When using a custom response, your workflow will have a limit of 55 seconds to reach the Response step. If your workflow does not reach the Response step in that time, the HTTP request will respond with a 542 status code to indicate a response timeout.

A 542 status code does not indicate that your workflow was unsuccessful; your workflow may still be running, but the results were not processed in time to provide a synchronous response. The timeout response will be returned as a JSON body which includes the workflow execution ID for your reference.

You can use this ID to retrieve results using the Task History API or to view results in the dashboard's Task History view.

• Link to view execution in Task History: https://dashboard.useparagon.com/connect/projects/[Project ID]/history/workflows/[Workflow ID]/executions/[Workflow Execution ID]

Example timeout response

{
    "message": "Workflow has been enqueued but has not completed.",
    "dateSubmitted": "2024-09-24T01:07:13.658Z",
    "projectId": "...",
    "workflowId": "...",
    "executionId": "..."
}