For the complete documentation index, see llms.txt. This page is also available as Markdown.

Backend custom events

Backend custom events are backend workflows you can trigger from the frontend. Learn how they differ from API workflows, and how parameters, return values, and privacy rules work.

A backend custom event is a backend workflow that you can trigger from the frontend. If you've used custom events on a page, the idea is the same: You run a set of actions from another workflow, wait for them to finish, and get a result back. The difference is that the work happens on Bubble's server.


How backend custom events differ from API workflows

Backend custom events are similar to API workflows, with a few key differences:

Backend custom events
API workflows

Privacy rules

You choose whether to respect or ignore them directly on the Trigger backend custom event action.

You choose at the workflow level.

Scheduling

They aren't scheduled, which makes them slightly more performant.

They're scheduled.

Triggering workflow

Pauses until the event finishes, just like with a frontend custom event.

Doesn't wait for the API workflow to finish.

External apps

Can't trigger them. They're only accessible from within your own app.

Can trigger them when they're set up with a public endpoint.

Even when you override privacy rules, the data you return is still subject to them. See Privacy rules and return data.


Parameters

Parameters are values passed from the triggering workflow to the backend custom event. They let the event work with different inputs each time it runs, while the logic inside stays the same.

To set up parameters, open the backend custom event and define each parameter in its properties. Each parameter has a name and a type, such as text, number, date, or a specific data type like User or Post.

When you call the event with the Trigger backend custom event action, the parameters appear as dynamic expression fields in the workflow property editor.


Return values

A backend custom event can return data to the workflow that triggered it. Return values are defined on the event itself, with a type and a label. Inside the event, use the Return data action to send a value back.

Once a return value is defined, the triggering workflow can use the result in later steps with Result of step X.


Privacy rules and return data

When a backend custom event is set to ignore privacy rules, the event itself runs with full access to the database. Any data returned to the triggering workflow is still subject to privacy rules in the calling context, though. For example, if the event returns a User, that user record is still filtered by the privacy rules that apply to the current user in the frontend.

To return information that would otherwise be hidden by privacy rules, return it in a format that isn't bound by them. For instance, instead of returning a User, return the user's name as text. The text value isn't subject to privacy rules, so the information can pass through.

This pattern is useful for answering specific questions or returning small pieces of data that the user wouldn't normally have access to, without exposing the underlying records.


Plan backend custom events with Bubble AI

The Bubble AI Agent can't build custom events in backend workflows. It can still explain how to set one up, and help you decide whether a backend custom event or an API workflow is the better fit.

Here are a few prompts to try:

Article: Edit apps with AI


FAQ: Backend custom events

Can an external app trigger a backend custom event?

No. They're only accessible from within your own app. If an external app needs to start a workflow, use an API workflow with a public endpoint.

Does the workflow wait for a backend custom event to finish?

Yes. The workflow that triggered the event pauses until it finishes before continuing.

If I override privacy rules, can users see everything the event returns?

No. Returned data is still subject to privacy rules, but if the event returns a single thing, Bubble sends its unique ID to the client. Protect all sensitive fields with privacy rules. See Privacy rules and return data.

How do I return data that privacy rules would hide?

Return it in a format that isn't bound by privacy rules. For instance, return the user's name as text instead of returning the User.

Last updated

Was this helpful?