Workflow API

The Workflow API lets you run workflows on a POST request. By using such endpoints, you can create things, sign users up, send emails, and leverage plugins to access external services. Define the workflows as you would for a normal page, action by action. Some actions are not available in this context, such as element-driven actions. Such an endpoint can return data, but for Read API calls, please use the Data API. You can create API workflows/endpoints after checking the box 'Enable Workflow API and backend workflows' in the API section in the Settings Tab. These workflows are defined in the Backend workflows page found in the Application Menu above the Palette.

General Workflow Endpoint

These are the workflows that you define in the Backend workflows page of the app in the Bubble Editor. The general path of the Workflow API follows this pattern or wf is for workflow.

API Event – Endpoint

This event is triggered when the server receives a request with the endpoint's name. The workflow only runs after the authentication passes. As with other workflows, you can set up conditions to restrict when the workflow runs.

Endpoint name

This is name of the endpoint used in the URL of the request endpoint_name. Each endpoint must have a unique name with no spaces. These errors are caught by the app Issue Checker.

Expose as a public endpoint

Check this box to allow requests from outside the Bubble Editor, either by a client that you built or another service, such as Stripe or Zapier. Non-public endpoints are useful for scheduled workflows and bulk operations that are defined in the Bubble Editor.

This endpoint can be run without authentication

Check this box if this call can be run without authentication. Use this to enable users to sign up or login to the app.

Ignore privacy rules when running the workflow

An API workflow is run based on the token sent. All privacy rules will apply. Sometimes, you may want the workflow to bypass these rules, even if run without authentication, and run as an admin user who has all rights to the data. Check this box to ignore the privacy rules.

Warning: Because these are security and privacy options, use this feature with caution.

Parameter definition

Parameters are the data the endpoint can accept. You can either list the different parameters one by one (Manual definition), or automatically detect the structure of the data when an external hits the endpoint. This type of detection is especially useful for webhooks.

Call parameters

Define which parameters the endpoint takes. Use this when you need to send data to Bubble's server, e.g., an email for signing the user up or information to create a new thing. This data should be set in the body of the POST request, except if you check the 'Querystring' box, in which case the parameter will be read from the URL as a querystring. Enter a key and define the data type. If this is a list, check 'Is a list/array.' If this parameter is optional, check 'Optional.' When a request is received, the Bubble workflow engine checks the validity of the data and returns a 400 error if the data is invalid. Note that if the parameter is set to 'Querystring', it will not be made available for scheduling actions, this feature should only be used if the service that hits the API requires to add the parameter in the URL. Access the value of the parameters in the subsequent actions of the workflows using the data source dropdown menu. You will see the parameters you defined at the top of the menu.

Include headers in the detected data

When the parameters are detected from an initialization request, you can include the request headers in the detected data if some important data is in them.

Detect data

Click this button to enter the initialization mode. After you have clicked this button, you should trigger a request to the endpoint, adding /initialize at the end of the URL. Once the request is detected, you'll be able to see the detected data and pick the data types (see below).

Modify types

Once an endpoint has been initialized, you can modify the data structure of the received object. You can ignore some keys, and modify the field type of each key, value to be able to use the data in subsequent actions.

Response type

The API can return a response as a JSON object, or redirect to a page in your app and return data as querystring. Using a 302 page redirect is useful when you call the endpoint from the browser.

Return a 200 if condition is not met

By default, Bubble will return a 400 error if the condition you've set on the workflow is not met. Check this box to change this setting and return a 200 code instead. Use this when the endpoint is used in a webhook, and the emitting source expects a 200 code.

Redirection on success

Pick here the page Bubble should redirect to at the end of the workflow. If the workflow returns data, it will be added as querystrings to the URL.

Redirection on error

Pick here the page Bubble should redirect to at when the workflow fails. The statusCode and the message will be added to the URL as querystrings.

Return data from API

This action defines which data should be returned by the API Workflow endpoint.

Return a plain text

Check this box to return a text instead of a JSON object.

Text to return

Define the text to return. It can be dynamic using the Composer.

List of parameters

These are the keys and data types of the parameters that are returned. When the name and type of data are set, define the data you want to return. In the case of the Workflow API, we limit the size of lists to 50 entries. For a full list of data, please use the Data API that handles pagination.