Trigger workflows with webhooks

You can automate a workflow to trigger whenever it receives a webhook event, such as a service monitoring alert or when a payment is received. The workflow can reference data in the event's JSON payload in the same way as other block data. If necessary, you can also configure a workflow to respond to webhook events using the Response block, returning data back to the webhook origin.

Configure webhook trigger settings

📘

Workflows are not triggered automatically by default. After verifying that a workflow runs as expected, toggle Enable.

Every workflow contains a Start block that contains Trigger settings for you to configure. Whenever these trigger conditions are met, the Start block triggers the workflow to run automatically. Select the Webhook trigger to configure a workflow to run when it receives a webhook event.

❗️

Any request sent to the specified endpoint will trigger the workflow. Do not share or publicize this information.

Every workflow has a unique webhook endpoint URL for receiving events. Use this URL when configuring webhook notifications from other services (e.g., Datadog or Stripe). Workflows can read data from a webhook event's JSON payload (e.g., error message or confirmation number) and make it available to your workflow. You can then use these parameters anywhere in your workflows with the startTrigger object.

Copy the endpoint URL and use it as the webhook event destination that will trigger webhook events. You can also copy the provided cURL command to manually invoke the webhook trigger as you build and test your workflow. This includes the endpoint URL to use.

You can optionally provide an example JSON input in the Start block that is used as a sample event payload when running the workflow from within the Workflow editor. The specified JSON is included in the cURL command.

Respond to webhook events

You can use Response blocks to configure custom responses to webhook events. This is useful if the workflow needs to return data to the origin.

By default, workflows triggered by webhook events immediately respond to the origin. When using a Response block, the workflow waits until the block has executed before responding. It then responds with the specified data.

Add a Response block to the workflow and ensure it's part of the control flow. You can specify the HTTP status code and a JSON response body to return, which can include any data from the workflow. For example, you could use a workflow to look up a customer's mailing address based on their email, which is returned in the webhook response.

Trigger workflows in Retool apps

You can trigger workflows from a Retool app using a query configured with the RESTQuery resource. The Response block makes it possible for Retool apps to also receive data back.

To trigger a workflow using a Retool app:

1. Copy the example cURL command from the workflow and extract the URL.
2. In the Retool app, create a new query and select the RESTQuery resource.
3. Set the Action type to POST and insert the workflow's endpoint URL.

You can pass data to the workflow by setting the query body to JSON and including relevant values. The Response block returns data that is available at {{ query.data }}.

Retool recommends you configure Response blocks to handle both successful and failed requests. This allows the sender to know if the workflow succeeded or if there was a problem, such as incorrect data or no results.