Skip to main content

Retool Events workflow quickstart

Learn how to build a workflow that uses Retool Events to send a notification when certain events occur within your organization.

With Retool Events, organization admins can build custom functionality in response to events in Retool. When a Retool Event occurs, an associated workflow with pre-defined parameters is triggered.

Follow this guide to learn how to set up workflows using Retool Events. In this example, the workflow sends custom emails to users invited to Retool, but you can customize your workflows however you'd like. See the Retool Events overview for more example use cases.

Requirements​

You must be an admin to configure Retool Events. Access to the workflows triggered by Retool Events is determined by existing workflow permissions.mdx).

Retool Events is available on Retool Cloud and self-hosted Retool versions 3.14 and later for organizations on the Enterprise plan.

Custom domains​

To disable Retool-branded emails and instead send emails from a custom domain, follow the guide to whitelabeling emails before you configure your workflows.

1. Configure Retool Event triggers​

From the Retool Events settings page under User Invited, select Add a workflow. If you add multiple workflows, they run in parallel.

Retool offers default workflow templates for common use cases with Retool Events, or you can build a workflow from scratch. The example in this guide uses the User Invited template, but you can customize the workflow as needed.

2. Configure the workflow​

Click the workflow you just added, and notice its startTrigger block shows the related Retool Event under Enabled triggers. This trigger is only configurable in the Retool Events settings page.

Next, you build workflow blocks using the workflow parameters.

Use parameters​

The Start blocks of template workflows have default inputs based on the event type. Retool passes these parameters to the workflow when events are triggered. To access them in workflows, use the syntax {{ startTrigger.data.parameterName }}.

invitedUserEmail​

string

The email address of the invited user.

string

The link to invite the user to Retool, usually in the form https://retool.com/auth/invite/sensitive-token.

inviteId​

number

The ID of the user invite.

Configure sending emails​

Many Retool lifecycle events are related to organization and user administration, so workflows triggered from Retool Events often involve sending emails. The User Invited template is pre-populated with a Resource query block using Retool Email, but you can configure this to use SendGrid or another email provider. See the guide to whitelabeling emails for more information.

The sendUserInvite block of the User Invited Template sends an email to the user invited to Retool, using the invitedUserEmail parameter as the To address. The email's body also contains links to the inviteLink parameter. When you construct your email blocks and templates, ensure you use the provided parameters to direct your users to the correct actions.

Connect to error handlers​

You may want to configure success and error handlers to your workflow, so you can log actions taken by users, emails sent, and any failed operations. At the bottom of the sendUserInvite block, click the Settings tab and select Continue. This ensures that any error from sendUserInvite flows to subsequent blocks connected to its error port. It's also useful to attach a block that triggers a notification or alert to notify your team of any failures.

3. Test the end-to-end flow​

After you configure your workflow, test the end-to-end invite flow by inviting a user to Retool or triggering your other action. Confirm your workflow is triggered and the user receives any configured notifications.

The Run history section in the Workflow IDE contains information about each workflow run, which can be useful for debugging. See the guide to troubleshooting workflows for more detail.